feat: add canHandleIntent to Structure Builder component

[cngonzalez]

Description

Some users would like to implement their own custom component within Structure, rather than just a desk list. However, this becomes difficult when trying to route to this component from other parts of the Studio, because there was no way for us to signal that this component could indeed handle that intent.

This PR takes the canHandleIntent argument available on lists and makes it available on components.

What to review

Is this a valid approach? Does it break inheritance of Structure Builder items in any way? Are there any gotchas?

Testing

This can be tried out in the test studio by adding a canHandleIntent to an S.component, like so:

      S.listItem()
        .id('translate')
        .title('Translate Test')
        .child(S.component(TranslateExample).id('example')
          .canHandleIntent((intent, params, context) =>  {
            console.log(intent, params, context)
            return true
          }
        )),

You should be able to run the Studio without crashing. When searching for a document, you should land on the canHandleIntent component.

A unit test is also included as part of this PR.

Notes for release

Custom components included in Structure (like S.component(MyCustomComponent)) can now be routed to from global search results or other links by using a canHandleIntent parameter.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
performance-studio	✅ Ready (Inspect)	Visit Preview		May 7, 2024 11:11am
test-next-studio	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 7, 2024 11:11am
test-studio	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 7, 2024 11:11am

1 Ignored Deployment

Name	Status	Preview	Comments	Updated (UTC)
studio-workshop	⬜️ Ignored (Inspect)	Visit Preview		May 7, 2024 11:11am

[github-actions]

No changes to documentation

[github-actions]

Component Testing Report Updated May 7, 2024 11:14 AM (UTC)

File	Status	Duration	Passed	Skipped	Failed
comments/CommentInput.spec.tsx	✅ Passed (Inspect)	35s	15	0	0
formBuilder/ArrayInput.spec.tsx	✅ Passed (Inspect)	6s	3	0	0
formBuilder/inputs/PortableText/Annotations.spec.tsx	✅ Passed (Inspect)	26s	6	0	0
formBuilder/inputs/PortableText/copyPaste/CopyPaste.spec.tsx	✅ Passed (Inspect)	31s	11	7	0
formBuilder/inputs/PortableText/Decorators.spec.tsx	✅ Passed (Inspect)	14s	6	0	0
formBuilder/inputs/PortableText/FocusTracking.spec.tsx	✅ Passed (Inspect)	37s	15	0	0
formBuilder/inputs/PortableText/Input.spec.tsx	✅ Passed (Inspect)	1m 7s	13	0	0
formBuilder/inputs/PortableText/ObjectBlock.spec.tsx	✅ Passed (Inspect)	1m 2s	18	0	0
formBuilder/inputs/PortableText/PresenceCursors.spec.tsx	✅ Passed (Inspect)	7s	3	9	0
formBuilder/inputs/PortableText/RangeDecoration.spec.tsx	✅ Passed (Inspect)	20s	9	0	0
formBuilder/inputs/PortableText/Styles.spec.tsx	✅ Passed (Inspect)	14s	6	0	0
formBuilder/inputs/PortableText/Toolbar.spec.tsx	✅ Passed (Inspect)	23s	9	0	0

[juice49]

I tested this in Studio, and it appeared to work correctly.

One thing I noticed is that the UserComponent doesn't seem to receive details about the handled intent (e.g. the intent type and document id) in its props.

The document id can be found via the router state (useRouterState), but it's a bit fiddly, and the developer must make the assumption that the final pane is the one containing the document (I'm not 100% sure this is always the case).

{
  "panes": [
    [
      {
        "id": "custom",
        "params": {}
      }
    ],
    [
      {
        "id": "component1",
        "params": {}
      }
    ],
    [
      {
        "id": "73bef166-639e-4313-bb5f-bbc5353869eb",
        "params": {}
      }
    ]
  ]
}

Is there a better way for developers to get details about the handled intent in their component? 🤔 I suspect this would generally be required to make useful intent-handling components. I'm wondering whether we should extend UserComponent to include the handled intent in its props as part of this change.

(I might be missing something obvious here!)

[cngonzalez]

Is there a better way for developers to get details about the handled intent in their component? 🤔 I suspect this would generally be required to make useful intent-handling components. I'm wondering whether we should extend UserComponent to include the handled intent in its props as part of this change.

It's a great question, I'm not sure! There's quite a bit of logic to get the information into the pane parameter in the props from the router (I think?). I can look into replicating that.

[juice49]

@cngonzalez Not to say that it's a blocker, necessarily. Just something I imagine developers might need in order to make use of this functionality.

[cngonzalez]

@cngonzalez Not to say that it's a blocker, necessarily. Just something I imagine developers might need in order to make use of this functionality.

I'm having a hard time getting to the bottom of resolving that information from the way Structure works 😅 I wonder if it's helpful to:

1. merge this as-is, to unblock some folks
2. provide an example of using the router, as you suggest, or even the URL (as is used elsewhere in the codebase)

What do you think?

[juice49]

I think that sounds reasonable. Great addition! 🥳