feat(10.1-02): mount plugin widget elements and run their actions from the form

- pluginAssets loads controller scripts and stylesheets from {base}/assets/ only, once per URL
- WidgetField mounts the custom element with attributes only and posts summer-action through the typed client
- Only declared fill keys returned by the server are patched; the form turns dirty and nothing saves
- widget is a registered valueless type rendered on create and update, labelled as a group
- backend::lang.extension strings in en and pl; embedded dist rebuilt

admin/src/components/form/FormField.vue

@@ -3,7 +3,7 @@ import { computed } from 'vue'
 import { CircleAlert } from '@lucide/vue'
 import type { ControllerParams, FormField, RelationOption } from '../../api/types'
 import FieldRenderer from './FieldRenderer.vue'
-import { ownsLabel } from './registry'
+import { groupLabelled, ownsLabel } from './registry'
 
 // One form row: label (600, red aria-hidden asterisk when required), the
 // control, the comment and the error line linked by aria-describedby.
@@ -25,6 +25,9 @@ const commentId = computed(() => `${base.value}-comment`)
 const errorId = computed(() => `${base.value}-error`)
 const invalid = computed(() => (props.errors?.length ?? 0) > 0)
 const selfLabelled = computed(() => ownsLabel(props.field.type))
+// A widget or partial row labels a role="group" host, so its label is a span
+// the host names with aria-labelledby, not a label for an input.
+const labelsGroup = computed(() => groupLabelled(props.field.type))
 const showComment = computed(() => !selfLabelled.value && !!props.field.comment)
 
 const describedBy = computed(() =>
@@ -36,7 +39,10 @@ const describedBy = computed(() =>
 
 <template>
   <div class="flex min-w-0 flex-col gap-1.5" :data-field="field.name">
-    <label v-if="!selfLabelled" :for="controlId" class="font-semibold">
+    <span v-if="labelsGroup" :id="`${controlId}-label`" class="font-semibold">
+      {{ field.label || field.name }}<span v-if="field.required" class="text-danger" aria-hidden="true"> *</span>
+    </span>
+    <label v-else-if="!selfLabelled" :for="controlId" class="font-semibold">
       {{ field.label || field.name }}<span v-if="field.required" class="text-danger" aria-hidden="true"> *</span>
     </label>
     <FieldRenderer

admin/src/components/form/fields/WidgetField.vue

@@ -0,0 +1,173 @@
+<script setup lang="ts">
+import { computed, inject, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { api } from '../../../api/client'
+import type { AdminRecord } from '../../../api/types'
+import { currentLocale, t } from '../../../app/i18n'
+import { showToast } from '../../../state/useToasts'
+import ExtensionFailure from '../../ui/ExtensionFailure.vue'
+import type { FieldControlProps } from '../control'
+import { FORM_ASSETS, FORM_LOCALE, FORM_PATCH, FORM_VALUES, WIDGET_EVENT, WIDGET_TIMEOUT } from '../formContext'
+
+// A `type: widget` field (D-04, D-05, D-07, D-08; UI-SPEC S3). The plugin's
+// custom element is created imperatively inside a node Vue never renders
+// children into. It gets attributes only: record id, field name, locale, the
+// current fill values as JSON and its labels; never a token, a cookie, a Vue
+// instance or a function. It asks for its action with a bubbling
+// summer-action event; the SPA posts it with the admin session, writes back
+// only the declared fill keys the server returned and shows the message.
+// Nothing is saved until the admin presses Save.
+const props = defineProps<FieldControlProps>()
+
+const values = inject(FORM_VALUES, null)
+const patch = inject(FORM_PATCH, () => undefined)
+const locale = inject(FORM_LOCALE, null)
+const assets = inject(FORM_ASSETS, () => Promise.resolve([]))
+
+const status = ref<'loading' | 'ready' | 'failed'>('loading')
+const mountPoint = ref<HTMLElement | null>(null)
+let element: HTMLElement | null = null
+let busy = false
+let unmounted = false
+
+/** The current values of the field's fill keys; absent values are left out. */
+function fillValues(): AdminRecord {
+  const current = values?.value ?? {}
+  const out: AdminRecord = {}
+  for (const name of props.field.fill ?? []) {
+    if (current[name] !== undefined) {
+      out[name] = current[name]
+    }
+  }
+  return out
+}
+
+const fillJson = computed(() => JSON.stringify(fillValues()))
+const localeName = computed(() => locale?.value || currentLocale.value)
+
+function timeout(ms: number): { promise: Promise<never>; cancel: () => void } {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const promise = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error('widget element was not defined in time')), ms)
+  })
+  return { promise, cancel: () => clearTimeout(timer) }
+}
+
+async function defined(tag: string): Promise<void> {
+  const failed = await assets()
+  if (customElements.get(tag)) {
+    return
+  }
+  if (failed.length > 0) {
+    throw new Error(`plugin script failed: ${failed.join(', ')}`)
+  }
+  const limit = timeout(WIDGET_TIMEOUT)
+  try {
+    await Promise.race([customElements.whenDefined(tag), limit.promise])
+  } finally {
+    limit.cancel()
+  }
+}
+
+function fail(text?: string): void {
+  showToast(text || t('backend::lang.extension.action_failed'), 'danger')
+  element?.setAttribute('state', 'error')
+}
+
+async function onAction(): Promise<void> {
+  const source = props.source
+  if (!element || busy || !source) {
+    return
+  }
+  busy = true
+  element.setAttribute('busy', '')
+  element.removeAttribute('state')
+  try {
+    const result = await api.POST('/{vendor}/{plugin}/{controller}/widgets/{field}', {
+      params: { path: { ...source, field: props.field.name } },
+      body: { record_id: props.recordId ?? undefined, values: fillValues() },
+    })
+    if (result.data) {
+      const fill = result.data.data.fill ?? {}
+      for (const name of props.field.fill ?? []) {
+        if (Object.hasOwn(fill, name)) {
+          patch(name, fill[name])
+        }
+      }
+      if (result.data.data.message) {
+        showToast(result.data.data.message)
+      }
+    } else {
+      fail(result.error?.error.message)
+    }
+  } catch {
+    fail()
+  } finally {
+    busy = false
+    element?.removeAttribute('busy')
+  }
+}
+
+function listener(): void {
+  void onAction()
+}
+
+onMounted(async () => {
+  const tag = props.field.widget ?? ''
+  try {
+    if (tag === '' || !props.source) {
+      throw new Error('widget field without a tag or controller')
+    }
+    await defined(tag)
+    if (unmounted || !mountPoint.value) {
+      return
+    }
+    const created = document.createElement(tag)
+    created.setAttribute('record-id', props.recordId == null ? '' : String(props.recordId))
+    created.setAttribute('field-name', props.field.name)
+    created.setAttribute('locale', localeName.value)
+    created.setAttribute('fill-values', fillJson.value)
+    created.setAttribute('label', props.field.actionLabel || props.field.label || props.field.name)
+    created.setAttribute('busy-label', t('backend::lang.extension.busy'))
+    created.addEventListener(WIDGET_EVENT, listener)
+    mountPoint.value.append(created)
+    element = created
+    status.value = 'ready'
+  } catch {
+    if (!unmounted) {
+      status.value = 'failed'
+    }
+  }
+})
+
+watch(fillJson, (json) => element?.setAttribute('fill-values', json))
+watch(localeName, (name) => element?.setAttribute('locale', name))
+
+onBeforeUnmount(() => {
+  unmounted = true
+  element?.removeEventListener(WIDGET_EVENT, listener)
+  element = null
+})
+</script>
+
+<template>
+  <ExtensionFailure
+    v-if="status === 'failed'"
+    :id="controlId"
+    data-widget-failed
+    :aria-describedby="describedBy || undefined"
+    :text="t('backend::lang.extension.widget_failed')"
+  />
+  <div
+    v-else
+    :id="controlId"
+    role="group"
+    data-widget-host
+    :aria-labelledby="`${controlId}-label`"
+    :aria-describedby="describedBy || undefined"
+    :aria-busy="status === 'loading' ? 'true' : undefined"
+    class="flex min-h-input items-center"
+  >
+    <span v-if="status === 'loading'" data-widget-skeleton class="h-[42px] w-[160px] rounded-control bg-skel" aria-hidden="true" />
+    <div ref="mountPoint" class="contents" />
+  </div>
+</template>

admin/src/components/form/formContext.ts

@@ -0,0 +1,28 @@
+// What a record form shares with extension controls (D-05, D-08). FormView
+// provides these; a widget reads the current values and the locale, and
+// writes action results back through patch, which marks the form dirty and
+// clears that field's errors exactly like typing into it. A form without a
+// provider (settings pages) gets the defaults of the injecting control.
+import type { InjectionKey, Ref } from 'vue'
+import type { AdminRecord } from '../../api/types'
+
+/** Read-only view of the form's current values. */
+export const FORM_VALUES: InjectionKey<Readonly<Ref<AdminRecord>>> = Symbol('summer.form.values')
+
+/** Sets one field's value as if the admin had edited it. Nothing is saved. */
+export const FORM_PATCH: InjectionKey<(name: string, value: unknown) => void> = Symbol('summer.form.patch')
+
+/** The form schema's locale (meta.locale). */
+export const FORM_LOCALE: InjectionKey<Readonly<Ref<string>>> = Symbol('summer.form.locale')
+
+/**
+ * The form controller's plugin assets: resolves once its scripts have loaded
+ * or failed, with the failed URLs (pluginAssets.loadControllerAssets).
+ */
+export const FORM_ASSETS: InjectionKey<() => Promise<string[]>> = Symbol('summer.form.assets')
+
+/** Event a widget element dispatches to run its action (bubbles, composed). */
+export const WIDGET_EVENT = 'summer-action'
+
+/** How long a widget waits for its custom element to be defined. */
+export const WIDGET_TIMEOUT = 5000

admin/src/components/form/registry.ts

@@ -3,7 +3,9 @@
 // dashed box, so an unknown type never breaks the form. The relation manager
 // is registered like any control but holds no form value: it edits its
 // relation through its own endpoints and renders only on an existing record.
-// Phase 10.1 turns this seam into the plugin extension point.
+// Phase 10.1 adds the plugin extension types: a widget mounts a plugin custom
+// element (D-04, D-09). It holds no form value either, but it renders on
+// create and update.
 import type { Component } from 'vue'
 import CheckboxField from './fields/CheckboxField.vue'
 import DropdownField from './fields/DropdownField.vue'
@@ -14,6 +16,7 @@ import SwitchField from './fields/SwitchField.vue'
 import TextField from './fields/TextField.vue'
 import TextareaField from './fields/TextareaField.vue'
 import UnsupportedField from './fields/UnsupportedField.vue'
+import WidgetField from './fields/WidgetField.vue'
 
 // The control helpers live in ./control so the field components never import
 // this module: registry -> field -> registry would be an import cycle whose
@@ -33,24 +36,34 @@ const renderers = new Map<string, Component>([
   ['checkbox', CheckboxField],
   ['relation', RelationField],
   [RELATION_MANAGER, RelationManager],
+  ['widget', WidgetField],
 ])
 
 /** Types whose control shows the label itself (toggle cards, relation manager). */
 const selfLabelled = new Set<string>(['switch', 'checkbox', RELATION_MANAGER])
 
 /**
- * Types that need a saved record and hold no form value: never rendered on
- * create, never part of the save body (D-05, design screen 5).
+ * Types that need a saved record: never rendered on create (D-05, design
+ * screen 5).
  */
 const recordBound = new Set<string>([RELATION_MANAGER])
 
+/** Types that hold no form value: never part of the save body (D-09). */
+const valueless = new Set<string>([RELATION_MANAGER, 'widget'])
+
+/**
+ * Types whose control is a group rather than one focusable element: the
+ * visible label is a span the group points at, not a label for an input.
+ */
+const groupLabelledTypes = new Set<string>(['widget'])
+
 export function rendererFor(type: string): Component {
   return renderers.get(type) ?? UnsupportedField
 }
 
 /** Whether the SPA can edit values of this field type. */
 export function isRegistered(type: string): boolean {
-  return renderers.has(type) && !recordBound.has(type)
+  return renderers.has(type) && !valueless.has(type)
 }
 
 /** Whether a field type renders only on an existing record (relation manager). */
@@ -61,3 +74,8 @@ export function needsRecord(type: string): boolean {
 export function ownsLabel(type: string): boolean {
   return selfLabelled.has(type)
 }
+
+/** Whether a field type's label labels a group (widget) instead of a control. */
+export function groupLabelled(type: string): boolean {
+  return groupLabelledTypes.has(type)
+}

admin/src/components/ui/ExtensionFailure.vue

@@ -0,0 +1,22 @@
+<script setup lang="ts">
+import { CircleAlert } from '@lucide/vue'
+
+// The extension failure box (UI-SPEC S5): UnsupportedField's geometry with a
+// danger icon, shown when a widget or partial could not be loaded. One line
+// sits centred in the 44px box; longer text wraps, the box grows with 10px
+// vertical padding and the icon stays on the first line.
+defineProps<{ text: string }>()
+</script>
+
+<template>
+  <div
+    role="alert"
+    data-extension-failure
+    class="flex min-h-input items-center rounded-control border-[1.5px] border-dashed border-border-strong bg-subtle px-3.5 py-2.5 text-[13px] text-muted"
+  >
+    <span class="flex min-w-0 items-start gap-2.5">
+      <CircleAlert :size="16" class="mt-0.5 shrink-0 text-danger" aria-hidden="true" />
+      <span class="min-w-0 [overflow-wrap:anywhere]">{{ text }}</span>
+    </span>
+  </div>
+</template>