feat(core): document layout

[hermanwikner]

Description

This pull request introduces document.components.layout to the Components API, enabling the customization of the document layout. The pull request also refactors the comments plugin to utilize this new capability within the Components API. As a result, all comments-specific logic that was previously implemented directly in desk is now removed and is instead configured in the comments plugin. That is, the comments feature is now entirely implemented as a plugin, utilizing existing APIs.

import {defineConfig} from 'sanity'
import {ContextProvider} from './ContextProvider'

export default defineConfig({
  // ...

  document: {
    components: {
      unstable_layout: (props) => {
        const {documentId, documentType} = props

        return (
          <ContextProvider documentId={documentId} documentType={documentType}>
            {props.renderDefault(props)}
          </ContextProvider>
        )
      },
    },
  },
})

Things to keep in mind:

• Unlike other components in the Components API, which are resolved in core and made available universally across all tools, the document.components.layout requires resolution within each individual tool. This is because there is no predefined concept of a specific document layout. That is, it is the responsibility of each individual tool to resolve the document layout component from the Components API middleware chain. To accomplish this, the useMiddlewareComponents hook can be used, which is exported from the sanity package (see example here in desk).
• Although the document.components.layout component receives the documentId and documentType in props, modifying these props passed to renderDefault will have no effect. This is because the documentId and documentType used in desk are resolved from the URL. That is, these props are currently being used as ‘read-only’ props in order to know which context you’re in.
• In the context of desk, which uses an advanced pane system layout, customizing the UI aspects of the document layout might lead to unexpected results and is not recommended. Instead, the API is best used as a way to add context providers to the document layout.

What to review

• Everything should work as usual
• Make sure that customizations made to document.components.layout are properly applied
• Removing the comments plugin from deskTool should remove the feature entirely and no errors should appear

Notes for release

N/A

[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		Dec 15, 2023 11:10am
studio-workshop	🔄 Building (Inspect)	Visit Preview	💬 Add feedback	Dec 15, 2023 11:10am
test-studio	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Dec 15, 2023 11:10am

[github-actions]

No changes to documentation

[github-actions]

Component Testing Report Updated Dec 15, 2023 11:13 AM (UTC)

File	Status	Duration	Passed	Skipped	Failed
comments/CommentInput.spec.tsx	✅ Passed (Inspect)	15s	15	0	0
formBuilder/ArrayInput.spec.tsx	✅ Passed (Inspect)	3s	3	0	0
formBuilder/inputs/PortableText/Annotations.spec.tsx	✅ Passed (Inspect)	8s	3	0	0
formBuilder/inputs/PortableText/Decorators.spec.tsx	✅ Passed (Inspect)	6s	6	0	0
formBuilder/inputs/PortableText/FocusTracking.spec.tsx	✅ Passed (Inspect)	16s	15	0	0
formBuilder/inputs/PortableText/Input.spec.tsx	✅ Passed (Inspect)	7s	9	0	0
formBuilder/inputs/PortableText/ObjectBlock.spec.tsx	✅ Passed (Inspect)	38s	18	0	0
formBuilder/inputs/PortableText/Styles.spec.tsx	✅ Passed (Inspect)	6s	6	0	0
formBuilder/inputs/PortableText/Toolbar.spec.tsx	✅ Passed (Inspect)	3s	3	0	0

[ricokahler]

I really like this API. It follows the same conventions for the studio.components API and enables a lot of cool plugins. I think this API could pair well with the changes I proposed in #4938 a while back.

I'd like to I think about refactoring the component resolution of all component API into the config resolver for consistency's sake but that's a different thing. This is a very solid API addition! Looking forward to discussing this in our Studio DX sync tomorrow!

[ricokahler]

very nice! love the refactors you did too!

[bjoerge]

Excellent work! Thanks for taking the time to add documentation and tests as well.