feat(nuxt): add setPageLayout utility (#6826)

[danielroe]

🔗 Linked issue

resolves nuxt/nuxt#14710

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

This adds a setPageLayout utility to handle complexities associated with changing layout keyed off of route.meta. Namely, it's complicated to persist the change from server -> client. This persists the server-set layout via a custom useState which is only used on the initial hydration. Subsequent layout changes are reactive and don't need to be hydrated.

Originally implemented by @516310460 ❤️

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[netlify]

✅ Deploy Preview for nuxt3-docs ready!

Name	Link
🔨 Latest commit	9861f36
🔍 Latest deploy log	https://app.netlify.com/sites/nuxt3-docs/deploys/630e4b3cf9c6ab0007e62e55
😎 Deploy Preview	https://deploy-preview-7075--nuxt3-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[pi0]

Following up nuxt/nuxt#14710, i understand there is a way to use prop binding for global usage of NuxtLayout but I'm thinking we could easily (what I suppose) use _layout state for default value of :name for <NuxtLayout>. This way utility can be already universal as setLayout.

[danielroe]

I did consider updating the default value but feel that it's not optimal. Consider this use case:

1. user visits a blog page (~/pages/blog/[slug].vue). This blog entry is full-width, so we set the layout to full-width using setPageLayout (so that it can be hydrated correctly on client-side).
2. user changes route to ~/pages/index.vue or ~/pages/about.vue. Now these are also displaying full-width layout unless there is a hard-coded definePageMeta({ layout: 'default }) in the page.

If we want to update the default layout (and I'm not sure we should) then a setDefaultLayout utility or similar might be a better approach.

[516310460]

I would like to know if there is a possibility of having more than one NuxtLayout in the page and if changing the _layout will be affected

<template>
  <div>
    <NuxtLayout>
      <template #header> Some header template content. default</template>
    </NuxtLayout>
    <NuxtLayout name="custom">
      <template #header> Some header template content. custom</template>
    </NuxtLayout>
    <NuxtLayout name="custom-two">
      <template #header> Some header template content. custom-two</template>
    </NuxtLayout>
  </div>
</template>

Link: https://stackblitz.com/edit/github-m7s6nu?file=pages%2Findex.vue

[pi0]

Makes sense to introduce setDefaultLayout utility for universal usage 👍🏼