Merge pull request #7160 from nextcloud-libraries/doc/guest-content

docs: clarify application containers and especially NcGuestContent

Author: susnux

docs/app-containers.md

@@ -0,0 +1,29 @@
+<!--
+ - SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+All applications **must** be wrapped in one of the provided app containers.
+Those containers provide base styling and context for all components.
+
+### Available containers
+#### `NcContent`
+This is the main container for all apps that provide full web-page interface.
+Its usual usage looks like this:
+
+```html static
+<NcContent>
+	<NcAppNavigation>
+		<!--- any in-app navigation -->
+	</NcAppNavigation>
+	<NcAppContent>
+		<!-- you application content -->
+	</NcAppContent>
+</NcContent>
+```
+
+#### `NcGuestContent`
+This is the main container for guest content like the login box of Nextcloud.
+It should only be used as the main container when rendering a page as `OCP\AppFramework\Http\TemplateResponse::RENDER_AS_GUEST`.
+
+<!-- TODO: Missing container for settings -->

src/components/NcGuestContent/NcGuestContent.vue

@@ -8,13 +8,15 @@
 Guest content container to be used for the guest content of your app.
 
 This components provides a wrapper around guest page content.
-It should be used as the main wrapper for public pages, similar to `NcContent`.
+It should be used as the main wrapper for guest pages, similar to `NcContent` for public and user pages.
+Meaning this component must be used as the root component for your application
+if you render the page using `OCP\AppFramework\Http\TemplateResponse::RENDER_AS_GUEST`.
 
 It can't be used multiple times on the same page.
 
 ### Usage
 
-```vue
+```html static
 <template>
 	<NcGuestContent>
 		<h2>Hello guest</h2>
@@ -26,6 +28,7 @@ It can't be used multiple times on the same page.
 
 <script setup lang="ts">
 import type { Slot } from 'vue'
+
 import { onMounted, onUnmounted } from 'vue'
 
 defineSlots<{

styleguide.config.cjs

@@ -192,6 +192,7 @@ module.exports = async () => {
 					'src/components/NcDashboard*/*.vue',
 					'src/components/NcDialog*/*.vue',
 					'src/components/NcEllipsisedOption*/*.vue',
+					'src/components/NcGuestContent/*.vue',
 					'src/components/NcHeader*/*.vue',
 					'src/components/NcListItem*/*.vue',
 					'src/components/NcPopover/NcPopoverTriggerProvider.vue',
@@ -203,47 +204,54 @@ module.exports = async () => {
 					'src/components/NcUserBubble/NcUserBubbleDiv.vue',
 				],
 				sections: [
-					{
-						name: 'NcActions',
-						components: [
-							// Put Actions component first
-							'src/components/NcActions/*.vue',
-							'src/components/NcAction[A-Z]*/*.vue',
-						],
-					},
 					{
 						name: 'App containers',
+						content: 'docs/app-containers.md',
 						components: [
-							'src/components/NcAppContent/NcAppContent.vue',
 							'src/components/NcContent/NcContent.vue',
+							'src/components/NcGuestContent/NcGuestContent.vue',
 						],
 						sections: [
 							{
-								name: 'NcAppNavigation',
-								components: [
-									'src/components/NcAppNavigation*/*.vue',
-								],
-								ignore: [
-									'src/components/NcAppNavigationItem/NcAppNavigationIconCollapsible.vue',
-									'src/components/NcAppNavigationItem/NcInputConfirmCancel.vue',
-								],
-							},
-							{
-								name: 'NcAppSidebar',
-								components: [
-									'src/components/NcAppSidebar/NcAppSidebar.vue',
-									'src/components/NcAppSidebarHeader/NcAppSidebarHeader.vue',
-									'src/components/NcAppSidebarTab/NcAppSidebarTab.vue',
-								],
-							},
-							{
-								name: 'NcAppSettings',
-								components: [
-									'src/components/NcAppSettings*/*.vue',
+								name: 'NcAppContent',
+								components: 'src/components/NcAppContent/NcAppContent.vue',
+								sections: [
+									{
+										name: 'NcAppNavigation',
+										components: [
+											'src/components/NcAppNavigation*/*.vue',
+										],
+										ignore: [
+											'src/components/NcAppNavigationItem/NcAppNavigationIconCollapsible.vue',
+											'src/components/NcAppNavigationItem/NcInputConfirmCancel.vue',
+										],
+									},
+									{
+										name: 'NcAppSidebar',
+										components: [
+											'src/components/NcAppSidebar/NcAppSidebar.vue',
+											'src/components/NcAppSidebarHeader/NcAppSidebarHeader.vue',
+											'src/components/NcAppSidebarTab/NcAppSidebarTab.vue',
+										],
+									},
+									{
+										name: 'NcAppSettings',
+										components: [
+											'src/components/NcAppSettings*/*.vue',
+										],
+									},
 								],
 							},
 						],
 					},
+					{
+						name: 'NcActions',
+						components: [
+							// Put Actions component first
+							'src/components/NcActions/*.vue',
+							'src/components/NcAction[A-Z]*/*.vue',
+						],
+					},
 					{
 						name: 'NcBreadcrumbs',
 						components: [