@brftech/filex-core 0.42.2 → 0.43.0

package/src/components/plugin/PluginPageView.vue

@@ -0,0 +1,339 @@
+<script setup lang="ts">
+/**
+ * PluginPageView — an app plugin's `page` view, drawn as a whole page.
+ *
+ * ⚠⚠ The SAME conversation a `modal` view has. `usePluginSurface` is the
+ * shared half (the surface, the values, the debounced `change`, the footer
+ * press, the `{op}` answer) and this file is only the frame: a title bar of
+ * its own, one column at reading width, the footer buttons at the bottom,
+ * and no dialog scroll inside a dialog. Writing a second conversation here
+ * is how a `page` wizard and a `modal` wizard start disagreeing about what
+ * `submit` sends.
+ *
+ * Its own two states, which a modal has no use for:
+ *   • QUEUED — a `page` action never goes through `…/run`, so the job is
+ *     born from this screen's submit. A tab that just closed itself would
+ *     leave the person with no idea whether anything happened; instead the
+ *     page says the job is queued and offers the way back to the operations
+ *     tray that is now tracking it.
+ *   • DONE — the plugin ended the conversation (`done`), with nothing queued.
+ *
+ * ⚠ It is in the package, not in the admin SPA: fm.example.com, the desktop shell
+ * and the embeds all reach `page` views through the same explorer, so a copy
+ * per host would be a copy per host to keep in step.
+ */
+import { computed, onMounted, ref, watch } from 'vue';
+import type { LocaleCode, ThemeMode } from '../../types/ExplorerConfig';
+import type { FileApi } from '../../composables/useFileApi';
+import { useLocale } from '../../composables/useLocale';
+import { usePluginSurface } from '../../composables/usePluginSurface';
+import { labelOf } from '../../lib/pluginLabel';
+import SurfaceConversation from './SurfaceConversation.vue';
+import SurfaceFooterButtons from './SurfaceFooterButtons.vue';
+import SurfaceSections from './SurfaceSections.vue';
+import { walkNodes } from '../../lib/surfaceValues';
+import { openTargetFor } from '../../lib/surfaceOpen';
+
+const props = defineProps<{
+  locale: LocaleCode;
+  theme?: ThemeMode;
+  api: FileApi;
+  plugin: string;
+  view: string;
+  /** Adapter-qualified path the page was opened on; echoed on every event. */
+  path?: string;
+  /** Storage names a file-chooser may span; where its picker opens. */
+  storages?: string[];
+  startAt?: string;
+  /** Where "back to the files" goes. Absent: the button is not drawn. */
+  backHref?: string;
+  /** Where the operations tray lives, for the queued state. */
+  opsHref?: string;
+  /**
+   * The prefix the SPA is served from (`/admin/`, `/drive/`) — what a
+   * `Surface.open` address is built against (v3 §3.0). Absent: the request
+   * is dropped, because a wrong address is worse than none.
+   */
+  mountBase?: string;
+  /**
+   * The CHROME around the conversation; the conversation itself is the same
+   * either way.
+   *
+   * `page` (the default) is a browser tab of its own: a title bar, one column
+   * at reading width, the viewport's height, a footer stuck to its bottom.
+   * `embedded` is the same screen drawn INSIDE a host's page — the admin
+   * panel's Apps section, an embed that already has a header — and brings
+   * none of those three, because the host has already said where the screen
+   * begins, how wide it is and what it is called.
+   *
+   * ⚠ A step carrying a document keeps the INLINE layout when embedded. The
+   * `page` rule fits a PDF to the VIEWPORT (v3 §3.2); inside a host's page
+   * the viewport is not this frame's box, so the same rule would fit the
+   * document to a height the frame does not have.
+   */
+  frame?: 'page' | 'embedded';
+  /**
+   * The section of a home page to open (`surface.sections`), as the host's
+   * address says. ⚠ The HOST owns it: choosing a section emits `section`
+   * and the host puts it in its URL, which comes back here — so Back walks
+   * the sections, and a link names one.
+   */
+  section?: string;
+}>();
+
+const emit = defineEmits<{
+  /** The server enqueued a job for this page; the raw ops row. */
+  (e: 'op', op: Record<string, unknown>): void;
+  /**
+   * The person chose another section of a home page — or, with
+   * `{replace: true}`, a page opened with NO section learned which one the
+   * plugin shows first: the address should name it without adding a step
+   * to history.
+   */
+  (e: 'section', id: string, how?: { replace?: boolean }): void;
+}>();
+
+const { t } = useLocale(() => props.locale);
+
+/** Drawn inside a host's page rather than in a tab of its own. */
+const embedded = computed(() => props.frame === 'embedded');
+
+type PageState = 'loading' | 'surface' | 'queued' | 'done' | 'error';
+const state = ref<PageState>('loading');
+const loadError = ref('');
+const toast = ref('');
+
+const conv = usePluginSurface(
+  {
+    api: props.api,
+    plugin: props.plugin,
+    view: props.view,
+    path: () => props.path,
+    locale: () => props.locale,
+    errorText: () => t('plugin.view.error'),
+  },
+  {
+    // ⚠ `onOp` fires BEFORE `onDone` (usePluginSurface posts them in that
+    // order), so the queued state has to be set after both — otherwise
+    // `onDone` would overwrite it with "finished" and the person would never
+    // see that a job is running.
+    /**
+     * v3 §3.0 — "go to this file, and start that screen on it".
+     *
+     * ⚠ A real navigation, not a tab: this IS a whole page, and the person
+     * asked to be taken to a document. The address is the explorer deep link
+     * a notification already uses, so the placement question is answered
+     * where it is answerable — the explorer knows which of the plugin's
+     * views is a `page` and opens that one in its own tab.
+     */
+    onOpen: (req) => {
+      const target = openTargetFor(req, { plugin: props.plugin, base: props.mountBase });
+      if (!target.href) return;
+      try {
+        if (target.newTab) {
+          const win = window.open(target.href, '_blank');
+          if (win) win.opener = null;
+          else window.location.assign(target.href);
+        } else {
+          window.location.assign(target.href);
+        }
+      } catch {
+        /* a blocked navigation leaves the screen as it is */
+      }
+    },
+    onOp: (op) => {
+      emit('op', op);
+      state.value = 'queued';
+    },
+    onDone: () => {
+      if (state.value !== 'queued') state.value = 'done';
+    },
+    onToast: (m) => (toast.value = m),
+  },
+);
+
+const current = conv.current;
+const title = computed(() => labelOf(current.value?.title, props.locale) || props.view);
+
+/**
+ * The section being shown. It starts from the host's address and follows
+ * it; a choice made here moves it at once (so the menu answers the click
+ * even in a host that does not keep an address), then tells the host.
+ */
+const wanted = ref(props.section ?? '');
+const sections = computed(() => current.value?.sections ?? []);
+/** Which entry is lit: what the plugin says it drew, else what was asked. */
+const activeSection = computed(() => current.value?.section || wanted.value);
+
+function chooseSection(id: string): void {
+  if (!id || id === activeSection.value) return;
+  wanted.value = id;
+  emit('section', id);
+  void load();
+}
+
+watch(
+  () => props.section,
+  (s) => {
+    const next = s ?? '';
+    // The host echoing the choice made above is not a new request.
+    if (next === wanted.value) return;
+    wanted.value = next;
+    void load();
+  },
+);
+
+async function load(): Promise<void> {
+  // ⚠ A section change keeps the page standing (menu and all) while the
+  // next table is fetched: a switch that blanked the screen to "Loading…"
+  // made the menu itself flash away under the pointer that chose it.
+  if (!current.value) state.value = 'loading';
+  loadError.value = '';
+  try {
+    // The section only when there is one: a page that has no menu asks the
+    // same question it always asked.
+    const res = wanted.value
+      ? await props.api.pluginView(props.plugin, props.view, props.path, wanted.value)
+      : await props.api.pluginView(props.plugin, props.view, props.path);
+    if (!res?.surface) {
+      loadError.value = t('plugin.view.error');
+      state.value = 'error';
+      return;
+    }
+    conv.setSurface(res.surface);
+    state.value = 'surface';
+    // ⚠ Opened without a section, the page shows the plugin's first choice
+    // — and the address has to say which, or choosing that same entry from
+    // the menu changes nothing (measured in the e2e round: a click on the
+    // lit "requested" left the URL bare), and a copied link opens wherever
+    // the plugin's default happens to be that day.
+    const shown = res.surface.section ?? '';
+    if (!wanted.value && shown) {
+      wanted.value = shown;
+      emit('section', shown, { replace: true });
+    }
+  } catch (e) {
+    // ⚠ An app's own error text never met the catalogue — isolate it.
+    loadError.value = t.foreign?.(String((e as Error)?.message ?? '')) || t('plugin.view.error');
+    state.value = 'error';
+  }
+}
+
+onMounted(() => void load());
+defineExpose({ reload: load });
+/**
+ * Is this step showing a DOCUMENT?
+ *
+ * ⚠⚠ v3 §3.2 — "in `page` placement the node takes the whole viewport
+ * minus the step header and footer, and fits the page to it". The complaint
+ * that started the round was a signature page you had to scroll in two
+ * directions: the document was fitted to a 960px text column inside a page
+ * that scrolled, so a portrait page ran off the bottom and the boxes were
+ * found by hunting.
+ *
+ * So the FRAME changes shape when the surface carries one: the header and
+ * the footer keep their size, the body becomes the remainder, and the node
+ * fits the page into it (`SurfacePdfFields.fitWidth`). Only then — an
+ * ordinary form step is still a readable column, and locking every step to
+ * the viewport would turn a four-field form into a tall empty screen.
+ */
+/**
+ * ⚠⚠ ...and only the step that REALLY shows one. A `pdf-fields` node in
+ * `define` mode draws no document at all — it is a column of cards, one per
+ * box — so shaping the frame to the window for it locked a growing list
+ * inside `height: 100vh; overflow: hidden` with no scroller of its own: the
+ * fourth box and everything after it sat below the fold, unreachable (the
+ * owner, 2026-09-23: "kutucukları oluşturduğumuz sayfada overflow hidden
+ * olduğu için aşağıda kalan ekstra kutucuklara kaydırarak gidemiyoruz").
+ * `place` and `edit` do carry the document and keep the window shape.
+ */
+const showsDocument = computed(() => {
+  let found = false;
+  walkNodes(conv.current.value?.nodes, (n) => {
+    if (n.type !== 'pdf-fields') return;
+    if ((n.props as { mode?: unknown } | undefined)?.mode === 'define') return;
+    found = true;
+  });
+  return found;
+});
+
+</script>
+
+<template>
+  <div
+    class="fe fe-apppage"
+    :class="[
+      theme === 'dark' ? 'fe--theme-dark' : theme === 'light' ? 'fe--theme-light' : '',
+      { 'is-doc': showsDocument && !embedded, 'fe-apppage--embedded': embedded },
+    ]"
+    data-testid="plugin-page"
+  >
+    <header v-if="!embedded" class="fe-apppage__bar">
+      <h1 class="fe-apppage__title" data-testid="plugin-page-title">{{ title }}</h1>
+      <p v-if="path" class="fe-apppage__path" :title="path">{{ path }}</p>
+      <a v-if="backHref" class="fe-btn fe-apppage__back" :href="backHref" data-testid="plugin-page-back">
+        {{ t('plugin.page_view.back') }}
+      </a>
+    </header>
+
+    <main class="fe-apppage__body">
+      <SurfaceSections
+        v-if="state === 'surface' && sections.length"
+        :sections="sections"
+        :active="activeSection"
+        :locale="locale"
+        :label="title"
+        :disabled="conv.busy.value"
+        @select="chooseSection"
+      />
+      <p v-if="state === 'loading'" class="fe-surface__text fe-surface__text--muted" data-testid="plugin-page-loading">
+        {{ t('plugin.view.loading') }}
+      </p>
+
+      <SurfaceConversation
+        v-else-if="state === 'surface'"
+        :conv="conv"
+        :locale="locale"
+        :theme="theme"
+        :api="api"
+        :plugin="plugin"
+        :storages="storages"
+        :start-at="startAt"
+        :toast="toast"
+        :layout="embedded ? 'inline' : 'page'"
+      />
+
+      <div v-else-if="state === 'queued'" class="fe-apppage__state" data-testid="plugin-page-queued">
+        <h2 class="fe-apppage__state-title">{{ t('plugin.page_view.queued_title') }}</h2>
+        <p class="fe-surface__text">{{ t('plugin.page_view.queued_text') }}</p>
+        <div class="fe-apppage__state-actions">
+          <a v-if="opsHref" class="fe-btn fe-btn--primary" :href="opsHref" data-testid="plugin-page-ops">
+            {{ t('plugin.page_view.open_ops') }}
+          </a>
+          <a v-if="backHref" class="fe-btn" :href="backHref">{{ t('plugin.page_view.back') }}</a>
+        </div>
+      </div>
+
+      <div v-else-if="state === 'done'" class="fe-apppage__state" data-testid="plugin-page-done">
+        <h2 class="fe-apppage__state-title">{{ t('plugin.page_view.done_title') }}</h2>
+        <p class="fe-surface__text">{{ t('plugin.page_view.done_text') }}</p>
+        <div class="fe-apppage__state-actions">
+          <a v-if="backHref" class="fe-btn fe-btn--primary" :href="backHref">{{ t('plugin.page_view.back') }}</a>
+        </div>
+      </div>
+
+      <div v-else class="fe-apppage__state" data-testid="plugin-page-error">
+        <h2 class="fe-apppage__state-title">{{ t('plugin.page_view.error_title') }}</h2>
+        <p v-if="loadError" class="fe-surface__error">{{ loadError }}</p>
+        <div class="fe-apppage__state-actions">
+          <button type="button" class="fe-btn" @click="load()">{{ t('plugin.page_view.retry') }}</button>
+          <a v-if="backHref" class="fe-btn" :href="backHref">{{ t('plugin.page_view.back') }}</a>
+        </div>
+      </div>
+    </main>
+
+    <footer v-if="state === 'surface' && conv.footer.value.length" class="fe-apppage__foot">
+      <SurfaceFooterButtons :conv="conv" :locale="locale" testid-prefix="plugin-page" />
+    </footer>
+  </div>
+</template>

package/src/components/plugin/PluginViewModal.vue

@@ -0,0 +1,159 @@
+<script setup lang="ts">
+/**
+ * PluginViewModal — the dialog an app plugin's `modal` view opens in (and
+ * the frame a `home` view is drawn in, full-size).
+ *
+ * The explorer hands it the first surface (the answer to `run`, or the
+ * `open` event of a view); from then on the conversation is
+ * `usePluginSurface`'s — the same one the inspector section holds — and
+ * this file is only the frame: title, size, the footer buttons, Close.
+ * When the server answers `{op}` the row goes up (`op`) and the dialog
+ * closes.
+ *
+ * ⚠ No iframe, no `v-html`, no script: SurfaceRenderer draws nodes with our
+ * own components and shows an unknown type as unknown.
+ *
+ * ⚠ The body and the buttons are `SurfaceConversation` / `SurfaceFooterButtons`
+ * — shared with the `page` frame and the public card, so a fix to any of the
+ * five things a surface body draws reaches all three.
+ */
+import { computed, watch } from 'vue';
+import type { LocaleCode, ThemeMode } from '../../types/ExplorerConfig';
+import type { FileApi } from '../../composables/useFileApi';
+import type { PluginSurface, SurfaceOpenRequest } from '../../types/Plugins';
+import { useLocale } from '../../composables/useLocale';
+import { usePluginSurface } from '../../composables/usePluginSurface';
+import { labelOf } from '../../lib/pluginLabel';
+import Modal from '../../modals/Modal.vue';
+import SurfaceConversation from './SurfaceConversation.vue';
+import SurfaceSections from './SurfaceSections.vue';
+import SurfaceFooterButtons from './SurfaceFooterButtons.vue';
+
+const props = defineProps<{
+  open: boolean;
+  locale: LocaleCode;
+  theme?: ThemeMode;
+  api: FileApi;
+  plugin: string;
+  view: string;
+  /** The first screen. */
+  surface: PluginSurface | null;
+  /** Adapter-qualified path of the row the view was opened on (echoed on every event). */
+  path?: string;
+  /** Storage names a file-chooser may span; where its picker opens. */
+  storages?: string[];
+  startAt?: string;
+  /** Forces the dialog size (a `home` view is drawn `xl`); else the surface's own. */
+  size?: 'sm' | 'md' | 'lg' | 'xl';
+}>();
+
+const emit = defineEmits<{
+  (e: 'close'): void;
+  /** The server enqueued a job for this view; the raw ops row. */
+  (e: 'op', op: Record<string, unknown>): void;
+  (e: 'toast', message: string): void;
+  /**
+   * v3 §3.0 — the answer says "go to this file". Reported UP rather than
+   * acted on here: the explorer is what can show a file and start a screen
+   * on it (`openAppTarget`), and a dialog navigating the window under itself
+   * would throw away the folder the person was standing in.
+   */
+  (e: 'open', req: SurfaceOpenRequest): void;
+}>();
+
+const { t } = useLocale(() => props.locale);
+
+const conv = usePluginSurface(
+  {
+    api: props.api,
+    plugin: props.plugin,
+    view: props.view,
+    path: () => props.path,
+    locale: () => props.locale,
+    errorText: () => t('plugin.view.error'),
+  },
+  {
+    onOp: (op) => emit('op', op),
+    onDone: () => emit('close'),
+    onToast: (m) => emit('toast', m),
+    onOpen: (req) => emit('open', req),
+  },
+);
+
+watch(
+  () => props.surface,
+  (s) => conv.setSurface(s),
+  { immediate: true },
+);
+
+const current = conv.current;
+const title = computed(() => labelOf(current.value?.title, props.locale) || props.view);
+/**
+ * A home page's menu, when a host with no page of its own draws one in this
+ * dialog (the degraded frame — an embed without `pluginPageBase`). There is
+ * no address to keep here, so a choice simply asks for that section.
+ */
+const sections = computed(() => current.value?.sections ?? []);
+async function chooseSection(id: string): Promise<void> {
+  if (!id || id === current.value?.section) return;
+  try {
+    const res = await props.api.pluginView(props.plugin, props.view, props.path, id);
+    if (res?.surface) conv.setSurface(res.surface);
+  } catch (e) {
+    // ⚠ An app's own error text never met the catalogue — isolate it.
+    emit('toast', t.foreign?.(String((e as Error)?.message ?? '')) || t('plugin.view.error'));
+  }
+}
+
+const size = computed<'sm' | 'md' | 'lg' | 'xl'>(() => {
+  if (props.size) return props.size;
+  const s = current.value?.size;
+  return s === 'sm' || s === 'lg' || s === 'xl' ? s : 'md';
+});
+</script>
+
+<template>
+  <Modal :open="open" :title="title" :size="size" :theme="theme" @close="emit('close')">
+    <div class="fe-plugin-view" data-testid="plugin-view">
+      <SurfaceSections
+        v-if="sections.length"
+        :sections="sections"
+        :active="current?.section"
+        :locale="locale"
+        :label="title"
+        :disabled="conv.busy.value"
+        @select="chooseSection"
+      />
+      <SurfaceConversation
+        :conv="conv"
+        :locale="locale"
+        :theme="theme"
+        :api="api"
+        :plugin="plugin"
+        :storages="storages"
+        :start-at="startAt"
+      />
+    </div>
+    <!-- ⚠ The frame's own Close only when the screen brought no buttons of
+         its own. A plugin's footer already carries its way out (Cancel,
+         Back), the header has its ×, and Escape and an outside click close
+         the dialog — a "Close" beside the plugin's "Cancel" was two buttons
+         doing one thing (the converter's first step read "Kapat · Vazgeç ·
+         İleri", release-candidate sweep 2026-09-21). A screen with no
+         buttons at all — a result, a notice — still gets one, so no screen
+         is a dead end for a pointer. -->
+    <template #actions>
+      <button
+        v-if="!conv.footer.value.length"
+        type="button"
+        class="fe-btn"
+        :disabled="conv.busy.value"
+        data-testid="plugin-view-close"
+        @click="emit('close')"
+      >
+        {{ t('plugin.view.close') }}
+      </button>
+      <SurfaceFooterButtons :conv="conv" :locale="locale" testid-prefix="plugin-view" />
+    </template>
+  </Modal>
+</template>

package/src/components/plugin/SurfaceConversation.vue

@@ -0,0 +1,76 @@
+<script setup lang="ts">
+/**
+ * SurfaceConversation — the body of ANY screen a plugin is talking through.
+ *
+ * Three frames draw a plugin surface: the modal a `modal` view opens, the
+ * whole page a `page` view opens, and the card an outside participant gets
+ * at `/p/<token>`. The FRAME is what differs (a dialog, a document, a card);
+ * the body is the same five things every time — the nodes, the toast the
+ * answer carried, "working…", the failure, and the footer buttons.
+ *
+ * ⚠⚠ Written once for that reason. Three copies of this block existed by the
+ * time the `page` placement arrived, and the drift had already started: the
+ * modal showed no toast at all, so a plugin that answered `{toast}` from a
+ * dialog was simply not heard. Anything added here — a node type's wiring, a
+ * busy affordance, an aria role — now reaches all three frames or none.
+ */
+import type { LocaleCode, ThemeMode } from '../../types/ExplorerConfig';
+import type { PluginSurfaceStore } from '../../composables/usePluginSurface';
+import type { FileRefResolver } from '../../types/Plugins';
+import { useLocale } from '../../composables/useLocale';
+import SurfaceRenderer, { type SurfaceApi } from './SurfaceRenderer.vue';
+
+const props = defineProps<{
+  /** The conversation this body belongs to (`usePluginSurface`). */
+  conv: PluginSurfaceStore;
+  locale: LocaleCode;
+  theme?: ThemeMode;
+  /** Absent in a bare render (the public page has no explorer API). */
+  api?: SurfaceApi;
+  /** The plugin the surface belongs to — the people-picker's lookup asks for it. */
+  plugin?: string;
+  storages?: string[];
+  startAt?: string;
+  /** A public page's exposed copies (`pub:N`) → a URL the browser may load. */
+  fileUrl?: FileRefResolver;
+  /** The last toast the frame collected, if it shows one inline. */
+  toast?: string;
+  /**
+   * v3 §3.2 — `page` lets a `pdf-fields` node take the viewport instead of
+   * sitting in the document flow. The FRAME knows which it is; the nodes do
+   * not, and must not guess from the window size (an embed in a narrow
+   * column is not a page).
+   */
+  layout?: 'inline' | 'page';
+  /** Where the document may grow to in `page` layout — the frame's own box. */
+  pageHeight?: string;
+}>();
+
+const { t } = useLocale(() => props.locale);
+</script>
+
+<template>
+  <SurfaceRenderer
+    v-if="conv.current.value"
+    :nodes="conv.current.value.nodes ?? []"
+    :locale="locale"
+    :theme="theme"
+    :errors="conv.errors.value"
+    :values="conv.values.value"
+    :api="api"
+    :plugin="plugin"
+    :storages="storages"
+    :start-at="startAt"
+    :file-url="fileUrl"
+    :layout="layout"
+    :page-height="pageHeight"
+    :invalid-keys="conv.invalidKeys.value"
+    :disabled="conv.busy.value"
+    @update:values="conv.updateValues"
+    @change="conv.scheduleChange"
+    @action="conv.rowAction"
+  />
+  <p v-if="toast" class="fe-surface__text fe-surface__text--info" role="status">{{ toast }}</p>
+  <p v-if="conv.busy.value" class="fe-surface__text fe-surface__text--muted">{{ t('plugin.view.busy') }}</p>
+  <p v-if="conv.failure.value" class="fe-surface__error" role="alert">{{ conv.failure.value }}</p>
+</template>

package/src/components/plugin/SurfaceFooterButtons.vue

@@ -0,0 +1,73 @@
+<script setup lang="ts">
+/**
+ * SurfaceFooterButtons — a surface's footer, wherever the frame puts it.
+ *
+ * The rule a plugin's buttons follow is not the frame's business: the
+ * primary one posts `submit`, every other one posts `action`, a `danger` one
+ * is red, and none of them is clickable while the conversation is busy
+ * (`usePluginSurface.press`). Three frames (dialog, page, public shell)
+ * place the row differently and must not each re-derive that.
+ *
+ * ⚠⚠ v3 §2 rule 3 — on a STEP (a surface carrying a `steps` node) the row is
+ * arranged rather than merely listed: Back on the left, one primary on the
+ * right, everything else between them, and a second `primary: true` is drawn
+ * as an ordinary button. `lib/surfaceSteps` holds the arrangement so the
+ * frames, the tests and the plugin test kit all read one answer.
+ *
+ * ⚠ `testidPrefix` is the one thing that legitimately differs per frame: the
+ * suites address the dialog's buttons and the page's separately, so a shared
+ * id would make a passing test ambiguous about which screen it measured.
+ */
+import { computed } from 'vue';
+import type { LocaleCode } from '../../types/ExplorerConfig';
+import type { PluginSurfaceStore } from '../../composables/usePluginSurface';
+import type { SurfaceAction } from '../../types/Plugins';
+import { labelOf } from '../../lib/pluginLabel';
+import { hasSteps, stepFooter } from '../../lib/surfaceSteps';
+
+const props = defineProps<{
+  conv: PluginSurfaceStore;
+  locale: LocaleCode;
+  /** `plugin-view` → `data-testid="plugin-view-action-<id>"`. */
+  testidPrefix: string;
+  /** The inspector's row is compact; every other frame uses the full size. */
+  small?: boolean;
+}>();
+
+const stepped = computed(() => hasSteps(props.conv.current.value?.nodes));
+
+const arranged = computed(() => stepFooter(props.conv.footer.value, stepped.value));
+
+/** Back, the ordinary buttons, then the one primary — in that DOM order. */
+const ordered = computed<SurfaceAction[]>(() => {
+  const f = arranged.value;
+  return [...(f.back ? [f.back] : []), ...f.others, ...(f.primary ? [f.primary] : [])];
+});
+
+/** Only the arranged primary is primary; a plugin's second one is not. */
+function isPrimary(a: SurfaceAction): boolean {
+  if (!stepped.value) return a.primary === true;
+  return a === arranged.value.primary;
+}
+</script>
+
+<template>
+  <button
+    v-for="a in ordered"
+    :key="a.id"
+    type="button"
+    class="fe-btn"
+    :class="{
+      'fe-btn--sm': small,
+      'fe-btn--primary': isPrimary(a) && !a.danger,
+      'fe-btn--danger': a.danger,
+      'fe-surface__back': stepped && a === arranged.back,
+    }"
+    :disabled="props.conv.busy.value || a.disabled"
+    :data-testid="`${testidPrefix}-action-${a.id}`"
+    @click="props.conv.press(a)"
+  >
+    {{ labelOf(a.label, locale) }}
+  </button>
+</template>
+