docs(administration): Vue single file component extension documentation

.wordlist.txt

@@ -228,6 +228,7 @@
 Cognito
 CommercialB
 CommercialBundle
+CommonJS
 ComponentFactory
 Composables
 ConfigJson
@@ -1345,12 +1346,14 @@
 codebase
 codeblock
 codeblocks
+codemod
 codemods
 codereview
 colorpicker
 compatability
 componentSectionRenderer
 composable
+composables
 config
 configComponent
 configs
@@ -1442,6 +1445,7 @@
 dereferenced
 describeFeatures
 destructure
+destructured
 destructuring
 dev
 devenv
@@ -1513,6 +1517,7 @@
 failover
 fallback
 fallbacks
+fallthrough
 fastly
 favicon
 fetchable
@@ -1636,10 +1641,12 @@
 initialisms
 initializer
 initializers
+inlines
 installable
 instantiation
 integrations
 interceptable
+interop
 intl
 invalidations
 io
@@ -1813,6 +1820,7 @@
 otlp
 overridable
 overrideComponentSetup
+overrideable
 oversales
 paas
 packagist
@@ -2032,6 +2040,7 @@
 snackbars
 snakeCase
 sortings
+sourcemap
 sourcemaps
 sql
 src
@@ -2076,6 +2085,8 @@
 supervisord
 svg
 sw
+swDefineOverride
+swDefinePublic
 swSelect
 sw_extends
 swoole
@@ -2147,8 +2158,11 @@
 uninstallation
 uniqBy
 unminified
+unmount
+unmounting
 unprefixed
 unregister
+unregisters
 unrequested
 unsecure
 unserialize
@@ -2163,7 +2177,35 @@
 uri
 url
 urls
+useBlockContext
+useCmsElement
+useCmsElementDeprecated
+useCmsState
+useContext
+useInlineSnippet
+useListing
+useMediaGridListener
+useMediaSidebarModal
+useModuleIconColors
+useNotification
+useNotificationTranslation
+usePlaceholder
+usePosition
+useRuleBetweenOperator
+useRuleContainer
+useSalutation
+useSession
+useSnackbar
+useSwContext
+useSwPreviousState
+useSwProps
+useSystem
+useTheme
+useTranslateWithFallback
+useUserSettings
+useValidation
 useValidityRange
+useVideoCover
 userAware
 userRecovery
 userland

guides/plugins/plugins/administration/single-file-components/api-reference/block-components/index.md

@@ -0,0 +1,51 @@
+---
+nav:
+  title: Block components
+  position: 30
+
+---
+
+# Block components
+
+<!--@include: ../../../../../../../snippets/guide/administration_sfc_experimental.md-->
+
+Two globally registered components carry the native block system. You write the tags without importing anything.
+
+<PageRef page="sw-block" title="sw-block" sub="Declare an extension point, or contribute to one" />
+<PageRef page="sw-block-parent" title="sw-block-parent" sub="Render what the extension point held before you" />
+
+## The model
+
+A component **declares** an extension point by wrapping markup in `<sw-block name="…">`. Its children are the default content, and with nothing registered against the name it renders as though the wrapper were not there.
+
+An override **contributes** to that point with `<sw-block extends="…">`. That tag renders nothing where it stands: it registers its content, and the matching `<sw-block name>` renders it wherever that happens to be.
+
+```html
+<!-- swag-greeting-card.vue -->
+<sw-block name="swag_greeting_card_body">
+    <p>Default content</p>
+</sw-block>
+
+<!-- swag-greeting-card.override.vue -->
+<sw-block extends="swag_greeting_card_body">
+    <sw-block-parent />
+    <p>Mine, underneath</p>
+</sw-block>
+```
+
+## Names
+
+A block name is a plain string and nothing validates it, so a typo matches nothing and fails silently. Names must be unique per component.
+
+The convention is an owner prefix, then the path through the component, in `snake_case`:
+
+```text
+sw_product_detail_base_price_form
+swag_greeting_card_body
+```
+
+Core uses `sw_`; a plugin uses its own prefix. A block you find in core is covered by the backwards-compatibility promise, so you can rely on it until the next major version.
+
+## Chains
+
+Several overrides may target one block. They stack in registration order, and each one's `<sw-block-parent />` renders the previous one's output rather than the original default. Leaving `<sw-block-parent />` out replaces everything below it, which is how one plugin removes another plugin's contribution.

guides/plugins/plugins/administration/single-file-components/api-reference/block-components/sw-block-parent.md

@@ -0,0 +1,47 @@
+---
+nav:
+  title: sw-block-parent
+  position: 70
+
+---
+
+# `sw-block-parent`
+
+<!--@include: ../../../../../../../snippets/guide/administration_sfc_experimental.md-->
+
+```html
+<sw-block-parent />
+```
+
+Takes no props. Renders whatever the extension point held before this override: the default content, or the previous override in the chain. Globally registered, so you write the tag without importing anything.
+
+Leave it out and the original markup is replaced.
+
+## Position decides yours
+
+```html
+<!-- append -->
+<sw-block extends="swag_greeting_card_body">
+    <sw-block-parent />
+    <p>I go after</p>
+</sw-block>
+
+<!-- prepend -->
+<sw-block extends="swag_greeting_card_body">
+    <p>I go before</p>
+    <sw-block-parent />
+</sw-block>
+
+<!-- replace -->
+<sw-block extends="swag_greeting_card_body">
+    <p>The original content is gone</p>
+</sw-block>
+```
+
+## Render it once, unconditionally
+
+It claims its position in the chain when it is created, so a `v-if` on it, or a `v-for` around it, corrupts that chain. One `<sw-block-parent />` per extending block, always rendered.
+
+## Chains
+
+When several overrides target one block they stack, and each one's `<sw-block-parent />` renders the previous one's output rather than the original default. That is what keeps other plugins on the page when your own change is additive.

guides/plugins/plugins/administration/single-file-components/api-reference/block-components/sw-block.md

@@ -0,0 +1,61 @@
+---
+nav:
+  title: sw-block
+  position: 60
+
+---
+
+# `sw-block`
+
+<!--@include: ../../../../../../../snippets/guide/administration_sfc_experimental.md-->
+
+The extension point. Globally registered, so you write the tag without importing anything. Which prop you pass decides what it does.
+
+| Prop      | Type     | Meaning                                                                              |
+| --------- | -------- | ------------------------------------------------------------------------------------ |
+| `name`    | `string` | **Declares** an extension point. Its children are the default content                |
+| `extends` | `string` | **Contributes** to the extension point of that name. Renders nothing where it stands |
+
+`name` and `extends` are the only props you write. The component has others - your editor may offer them - and they are internal: the build rejects an authored `data`, `v-bind` or `#default` on an `sw-block`.
+
+## Declaring an extension point
+
+```html
+<sw-block name="swag_greeting_card_body">
+    <p>Default content</p>
+</sw-block>
+```
+
+With nothing registered against the name, this renders as though the wrapper were not there.
+
+## Contributing to one
+
+```html
+<sw-block extends="swag_greeting_card_body">
+    <sw-block-parent />
+    <p>Mine, underneath</p>
+</sw-block>
+```
+
+The target block is replaced by what goes inside. To keep what was there, render [`sw-block-parent`](sw-block-parent).
+
+An `<sw-block extends>` belongs at the root of an override's template and cannot be nested inside another element. Where it sits does not affect where its content renders: it registers the content, and the matching `<sw-block name>` renders it.
+
+## Names
+
+Block names are strings and nothing validates them, so a typo silently matches nothing. They must be unique per component. The convention is an owner prefix and then the path through the component, in `snake_case`: core uses `sw_`, a plugin uses its own.
+
+```text
+sw_product_detail_base_price_form
+swag_greeting_card_body
+```
+
+## Bindings in block content
+
+Your override's bindings are available inside its `<sw-block extends>` content and read like any other Vue template binding. Mutating one from the template - `@click="counter++"` - is not supported; wrap the mutation in a function and call that instead.
+
+## Order, when several extensions meet
+
+Native `<sw-block extends>` contributions render in registration order, and all of them render after a TwigJS override of the same block. A legacy override is therefore always the parent of a native one, whichever order the plugins load in.
+
+<PageRef page="../../internals" title="Internals" sub="How the chain is assembled, and why the order is what it is" />

guides/plugins/plugins/administration/single-file-components/api-reference/composables/index.md

@@ -0,0 +1,98 @@
+---
+nav:
+  title: Composables
+  position: 20
+
+---
+
+# Composables
+
+<!--@include: ../../../../../../../snippets/guide/administration_sfc_experimental.md-->
+
+All composables the Administration offers are experimental. Their names, options and return values can
+still change without a deprecation, so pin down what you rely on and tell us when one of them does not
+fit what you are building.
+
+## Override composables
+
+Three of them are injected by the build like the macros are, so you never import them, and they exist
+only inside an `.override.vue` file. They are how an override reaches the component it overrides.
+
+<PageRef page="use-sw-previous-state" title="useSwPreviousState()" sub="The state of the component you override" />
+<PageRef page="use-sw-props" title="useSwProps()" sub="That component's props, read only" />
+<PageRef page="use-sw-context" title="useSwContext()" sub="That component's emit, attrs, slots and expose" />
+
+A base component needs none of them: it declares its own props with `defineProps()` and its own events
+with `defineEmits()`.
+
+## Administration composables
+
+Everything else is imported, one module per composable, named after it in `kebab-case`:
+
+```ts
+import { useNotification } from 'shopware:composables/use-notification';
+```
+
+Most of them are the Composition API side of a mixin. A mixin declared its own props and read them off
+`this`; a composable has neither, so whatever the mixin used to take from its host is passed in, and
+getters keep it reactive:
+
+```ts
+const { isBetween, betweenValue } = useRuleBetweenOperator({
+    condition: () => props.condition,
+    ensureValueExist: () => emit('ensure-value-exist'),
+});
+```
+
+The mixins stay where they are, so an Options API component that has not been migrated keeps working.
+
+<PageRef page="../../../mixins-directives/using-mixins" title="Using mixins" sub="The Options API side, and what each mixin does" />
+
+### Notifications
+
+<PageRef page="use-notification" title="useNotification()" sub="The notifications in the top right, and the system ones" />
+<PageRef page="use-notification-translation" title="useNotificationTranslation()" sub="Translate and sanitize a notification for rendering" />
+<PageRef page="use-snackbar" title="useSnackbar()" sub="Add and remove snackbars" />
+
+### Session and context
+
+<PageRef page="use-session" title="useSession()" sub="The logged-in user, their privileges and the admin locale" />
+<PageRef page="use-system" title="useSystem()" sub="The locales the Administration has registered" />
+<PageRef page="use-context" title="useContext()" sub="The app and API context behind Shopware.Context" />
+<PageRef page="use-user-settings" title="useUserSettings()" sub="Read and write per-user config" />
+<PageRef page="use-theme" title="useTheme()" sub="The light or dark appearance, and the user's preference" />
+<PageRef page="use-module-icon-colors" title="useModuleIconColors()" sub="The opt-in colored module icons" />
+
+### Text and formatting
+
+<PageRef page="use-inline-snippet" title="useInlineSnippet()" sub="Resolve a snippet a merchant translated themselves" />
+<PageRef page="use-translate-with-fallback" title="useTranslateWithFallback()" sub="Translate against the active locale, then the fallback" />
+<PageRef page="use-placeholder" title="usePlaceholder()" sub="Read a translatable field the way the Administration displays it" />
+<PageRef page="use-salutation" title="useSalutation()" sub="Format a salutation, with its fallback" />
+
+### Lists and forms
+
+<PageRef page="use-listing" title="useListing()" sub="Pagination, sorting, search and selection, kept in the route" />
+<PageRef page="use-position" title="usePosition()" sub="The position integers of an entity collection" />
+<PageRef page="use-validation" title="useValidation()" sub="Run a value against the rules of the validation prop" />
+
+### Rule builder
+
+<PageRef page="use-rule-container" title="useRuleContainer()" sub="The state of a condition container in sw-condition-tree" />
+<PageRef page="use-rule-between-operator" title="useRuleBetweenOperator()" sub="Render a between operator as a from/to pair" />
+
+### Media
+
+<PageRef page="use-media-grid-listener" title="useMediaGridListener()" sub="Turn media grid events into a selection" />
+<PageRef page="use-media-sidebar-modal" title="useMediaSidebarModal()" sub="The media sidebar's modals, and what they report" />
+<PageRef page="use-video-cover" title="useVideoCover()" sub="Assign and remove a video's poster image" />
+
+### CMS
+
+<PageRef page="use-cms-state" title="useCmsState()" sub="The CMS editor state a block or config panel works against" />
+<PageRef page="use-cms-element" title="useCmsElement()" sub="An element's resolved config, and the writes that change it" />
+<PageRef page="use-cms-element-deprecated" title="useCmsElementDeprecated()" sub="What the codemod targets, and how to move off it" />
+
+### Block system
+
+<PageRef page="use-block-context" title="useBlockContext()" sub="The registry behind sw-block" />