@revenexx/studio-shared 0.3.0 → 0.3.1

package/dist/runtime/components/DataTable/DataTable.vue.d.ts

@@ -20,6 +20,7 @@ declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>
         filter?: boolean | {
             width?: string;
             active?: boolean;
+            count?: number;
         };
         /** Built-in status/dimension filter pills (static mode). One dimension, or
          *  several (each renders as its own sub-menu). */
@@ -32,6 +33,26 @@ declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>
         viewModes?: DataTableViewMode[] | null;
         /** Collapse handle for the surface's left rail (see `ListSurface`). */
         rail?: boolean | DataTableRail;
+        /**
+         * Scroll the ROWS inside the table instead of the page.
+         *
+         * The toolbar, the header and the footer stay put and only the data moves,
+         * so paging through a long list keeps the search box, the filters and the
+         * "showing 20 of 400" in view — you stay in the table's context instead of
+         * scrolling the whole surface away and losing the controls that scope it.
+         *
+         * OPT-IN. A short list scrolling inside a box shorter than the list is worse
+         * than a page that scrolls, and there is no way for this component to know
+         * which it is looking at.
+         *
+         * The header row moves INSIDE the scroll container and sticks, rather than
+         * sitting above it. That is not a detail: a scrollbar takes width from the
+         * scrolling box, so a header outside it stays wider than the rows and every
+         * column drifts by however wide the scrollbar is.
+         */
+        scrollBody?: boolean | {
+            maxHeight?: string;
+        };
         pagination?: boolean | {
             pageSize?: number;
         };
@@ -61,12 +82,12 @@ declare const _default: <T>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>
         }) => any) | undefined;
     } & {
         'filter-menu'?: (props: {}) => any;
+    } & {
+        scope?: (props: {}) => any;
     } & {
         'toolbar-left'?: (props: {}) => any;
     } & {
         'toolbar-right'?: (props: {}) => any;
-    } & {
-        scope?: (props: {}) => any;
     } & {
         actions?: (props: {}) => any;
     } & {

package/dist/runtime/components/DataTable/FilterMenu.d.vue.ts

@@ -1,12 +1,14 @@
 type __VLS_Props = {
     /** Popover width class (a wide panel of inputs needs more than the default). */
     width?: string;
-    /** Tint the trigger while at least one filter is set. */
+    /** The trigger goes primary while at least one filter is set. */
     active?: boolean;
+    /** How many are set, for the badge. */
+    count?: number;
 };
-declare var __VLS_34: {};
+declare var __VLS_22: {};
 type __VLS_Slots = {} & {
-    default?: (props: typeof __VLS_34) => any;
+    default?: (props: typeof __VLS_22) => any;
 };
 declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
     active: boolean;

package/dist/runtime/components/DataTable/FilterMenu.vue

@@ -1,46 +1,42 @@
 <script setup>
-import { AltArrowDown, Filter } from "#solar-icons";
-import {
-  Button,
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuLabel,
-  DropdownMenuSeparator,
-  DropdownMenuTrigger
-} from "@revenexx/studio";
+import { Filter } from "#solar-icons";
+import { Popover, PopoverContent, PopoverTrigger, ToolbarFilterTrigger } from "@revenexx/studio";
 defineProps({
-  width: { type: String, required: false, default: "w-56" },
-  active: { type: Boolean, required: false, default: false }
+  width: { type: String, required: false, default: "w-72" },
+  active: { type: Boolean, required: false, default: false },
+  count: { type: Number, required: false }
 });
 const t = useT();
 </script>
 
 <template>
-  <DropdownMenu>
-    <DropdownMenuTrigger as-child>
-      <Button
-        variant="outline"
-        size="sm"
-        class="h-7 gap-1.5 text-sm"
-        :class="active ? 'border-primary/30 text-primary' : ''"
-        :aria-label="t('shared.datatable.filtermenu.aria')"
+  <Popover>
+    <PopoverTrigger as-child>
+      <ToolbarFilterTrigger
+        icon-only
+        :active="active"
+        :count="count"
+        :label="t('shared.datatable.filtermenu.aria')"
       >
-        <Filter :size="14" />
-        {{ t("shared.datatable.filtermenu.action") }}
-        <AltArrowDown :size="12" class="opacity-60" />
-      </Button>
-    </DropdownMenuTrigger>
-    <DropdownMenuContent align="start" :class="width">
-      <DropdownMenuLabel class="text-sm text-muted-foreground">
+        <template #icon>
+          <Filter :size="14" weight="BoldDuotone" />
+        </template>
+      </ToolbarFilterTrigger>
+    </PopoverTrigger>
+
+    <PopoverContent align="start" :class="['p-0', width]">
+      <p class="px-4 pt-3 pb-1 text-sm text-muted-foreground">
         {{ t("shared.datatable.filtermenu.heading") }}
-      </DropdownMenuLabel>
-      <DropdownMenuSeparator />
-      <slot>
-        <DropdownMenuItem disabled>
-          {{ t("shared.datatable.filtermenu.empty") }}
-        </DropdownMenuItem>
-      </slot>
-    </DropdownMenuContent>
-  </DropdownMenu>
+      </p>
+      <!-- The surface's controls, stacked. Full width, because a filter panel
+           holding a half-width select looks like something failed to load. -->
+      <div class="space-y-2.5 p-4 pt-2 [&_[data-slot=select-trigger]]:w-full">
+        <slot>
+          <p class="py-4 text-center text-sm text-muted-foreground">
+            {{ t("shared.datatable.filtermenu.empty") }}
+          </p>
+        </slot>
+      </div>
+    </PopoverContent>
+  </Popover>
 </template>

package/dist/runtime/components/DataTable/FilterMenu.vue.d.ts

@@ -1,12 +1,14 @@
 type __VLS_Props = {
     /** Popover width class (a wide panel of inputs needs more than the default). */
     width?: string;
-    /** Tint the trigger while at least one filter is set. */
+    /** The trigger goes primary while at least one filter is set. */
     active?: boolean;
+    /** How many are set, for the badge. */
+    count?: number;
 };
-declare var __VLS_34: {};
+declare var __VLS_22: {};
 type __VLS_Slots = {} & {
-    default?: (props: typeof __VLS_34) => any;
+    default?: (props: typeof __VLS_22) => any;
 };
 declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
     active: boolean;

package/dist/runtime/components/DataTable/types.d.ts

@@ -46,8 +46,21 @@ export interface DataTableFilter<T = unknown> {
     key?: string;
     /** Sub-menu title, e.g. "Status" (default `Status`). */
     label?: string;
-    /** The row's value for this dimension (e.g. `r => r.status`). */
-    getter: (row: T) => string | null | undefined;
+    /**
+     * The row's value(s) for this dimension.
+     *
+     * A string for anything a row has exactly one of — `r => r.status`. An ARRAY
+     * where a row can have several, and that is not a convenience: modelled as
+     * one value, `r => r.locales.join(', ')` makes the SET the value, so the
+     * options become combinations (four languages produce up to fifteen, six up
+     * to sixty-three) and "which of these have Polish?" cannot be asked at all —
+     * the answer is spread across three options and none of the counts is it.
+     *
+     * With an array the row lands in every bucket it belongs to. The counts then
+     * overlap rather than sum to the row total, which is correct and looks like a
+     * bug; see `runtime/lib/dataTableFilters.ts`.
+     */
+    getter: (row: T) => string | string[] | null | undefined;
     /** The selectable values + their labels. */
     options: {
         value: string;

package/dist/runtime/components/Shared/FloatingPanel.d.vue.ts

@@ -0,0 +1,55 @@
+type Mode = 'docked-left' | 'docked-right' | 'floating';
+type __VLS_Props = {
+    /** What `useFloatingPanel` returned, passed through whole. */
+    panel: {
+        mode: {
+            value: Mode;
+        };
+        collapsed: {
+            value: boolean;
+        };
+        floatingStyle: {
+            value: Record<string, string>;
+        };
+        dragging: {
+            value: boolean;
+        };
+        startDrag: (ev: PointerEvent, el: HTMLElement | null) => void;
+        dock: (side: 'left' | 'right') => void;
+        floatHere: (el: HTMLElement | null) => void;
+        setCollapsed: (v: boolean) => void;
+    };
+    title: string;
+    /** Room the docked panel leaves at the bottom, for a floating control bar. */
+    bottomClass?: string;
+    /** Tailwind width, matching the `width` given to the composable. */
+    widthClass?: string;
+    /** Labels, so the package carries no copy of its own. */
+    labels: {
+        dockLeft: string;
+        dockRight: string;
+        floatHere: string;
+        collapse: string;
+        expand: string;
+        placement: string;
+    };
+};
+declare var __VLS_5: {}, __VLS_67: {}, __VLS_69: {};
+type __VLS_Slots = {} & {
+    'pill-icon'?: (props: typeof __VLS_5) => any;
+} & {
+    default?: (props: typeof __VLS_67) => any;
+} & {
+    footer?: (props: typeof __VLS_69) => any;
+};
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    bottomClass: string;
+    widthClass: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/Shared/FloatingPanel.vue

@@ -0,0 +1,118 @@
+<script setup>
+import { computed } from "vue";
+import { HamburgerMenu, MenuDots, Minimize } from "#solar-icons";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger
+} from "@revenexx/studio";
+const props = defineProps({
+  panel: { type: Object, required: true },
+  title: { type: String, required: true },
+  bottomClass: { type: String, required: false, default: "bottom-16" },
+  widthClass: { type: String, required: false, default: "w-80" },
+  labels: { type: Object, required: true }
+});
+const shell = ref(null);
+const shellClass = computed(() => {
+  if (props.panel.mode.value === "docked-left") return `left-3 top-3 ${props.bottomClass}`;
+  if (props.panel.mode.value === "docked-right") return `right-3 top-3 ${props.bottomClass}`;
+  return "max-h-[70vh]";
+});
+const pillClass = computed(() => {
+  if (props.panel.mode.value === "docked-left") return "left-3 top-3";
+  if (props.panel.mode.value === "docked-right") return "right-3 top-3";
+  return "";
+});
+</script>
+
+<template>
+  <Transition
+    enter-active-class="transition duration-150 ease-out"
+    enter-from-class="opacity-0 scale-95"
+    enter-to-class="opacity-100 scale-100"
+    leave-active-class="transition duration-100 ease-in"
+    leave-from-class="opacity-100 scale-100"
+    leave-to-class="opacity-0 scale-95"
+  >
+    <div
+      v-if="panel.collapsed.value"
+      key="pill"
+      class="absolute z-10"
+      :class="pillClass"
+      :style="panel.mode.value === 'floating' ? panel.floatingStyle.value : void 0"
+    >
+      <!-- Two-layer frame: outer glass ring, inner white pane — so the pill is
+           recognisably the same object as the panel it came from. -->
+      <div class="rounded-lg border border-gray-400/10 outline-1 outline-white/30 backdrop-blur-sm">
+        <button
+          type="button"
+          class="flex h-9 cursor-pointer items-center gap-1.5 rounded-lg bg-white px-3 text-sm font-medium transition hover:bg-muted/75"
+          :title="labels.expand"
+          @click="panel.setCollapsed(false)"
+        >
+          <slot name="pill-icon" />
+          {{ title }}
+        </button>
+      </div>
+    </div>
+
+    <div
+      v-else
+      key="panel"
+      ref="shell"
+      class="absolute z-10 flex flex-col rounded-lg border border-gray-400/10 outline-1 outline-white/30 backdrop-blur-sm"
+      :class="[shellClass, widthClass]"
+      :style="panel.mode.value === 'floating' ? panel.floatingStyle.value : void 0"
+    >
+      <div class="relative flex min-h-0 flex-1 flex-col overflow-hidden rounded-lg border border-white bg-white">
+        <div
+          class="flex shrink-0 touch-none select-none items-center gap-1 border-b border-black/[0.06] bg-white px-2 py-1.5"
+          :class="panel.dragging.value ? 'cursor-grabbing' : 'cursor-grab'"
+          @pointerdown="panel.startDrag($event, shell)"
+        >
+          <HamburgerMenu :size="14" class="shrink-0 text-muted-foreground/60" />
+          <span class="min-w-0 flex-1 truncate text-sm font-medium">{{ title }}</span>
+
+          <DropdownMenu>
+            <DropdownMenuTrigger as-child>
+              <button
+                type="button"
+                class="flex size-6 shrink-0 items-center justify-center rounded-md text-muted-foreground transition hover:bg-muted/50 hover:text-foreground"
+                :title="labels.placement"
+              >
+                <MenuDots :size="14" />
+              </button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end" class="w-36 rounded-lg border border-black/[0.06] bg-white p-1 shadow-lg">
+              <DropdownMenuItem class="rounded-md text-sm" @select="panel.dock('left')">{{ labels.dockLeft }}</DropdownMenuItem>
+              <DropdownMenuItem class="rounded-md text-sm" @select="panel.dock('right')">{{ labels.dockRight }}</DropdownMenuItem>
+              <DropdownMenuItem class="rounded-md text-sm" @select="panel.floatHere(shell)">{{ labels.floatHere }}</DropdownMenuItem>
+              <DropdownMenuSeparator class="my-1 h-px bg-black/[0.06]" />
+              <DropdownMenuItem class="rounded-md text-sm" @select="panel.setCollapsed(true)">{{ labels.collapse }}</DropdownMenuItem>
+            </DropdownMenuContent>
+          </DropdownMenu>
+
+          <button
+            type="button"
+            class="flex size-6 shrink-0 items-center justify-center rounded-md text-muted-foreground transition hover:bg-muted/50 hover:text-foreground"
+            :title="labels.collapse"
+            @click="panel.setCollapsed(true)"
+          >
+            <Minimize :size="14" />
+          </button>
+        </div>
+
+        <div class="flex min-h-0 flex-1 flex-col overflow-hidden">
+          <slot />
+        </div>
+
+        <div v-if="$slots.footer" class="shrink-0 border-t border-black/[0.06] px-3 py-2 text-xs text-muted-foreground">
+          <slot name="footer" />
+        </div>
+      </div>
+    </div>
+  </Transition>
+</template>

package/dist/runtime/components/Shared/FloatingPanel.vue.d.ts

@@ -0,0 +1,55 @@
+type Mode = 'docked-left' | 'docked-right' | 'floating';
+type __VLS_Props = {
+    /** What `useFloatingPanel` returned, passed through whole. */
+    panel: {
+        mode: {
+            value: Mode;
+        };
+        collapsed: {
+            value: boolean;
+        };
+        floatingStyle: {
+            value: Record<string, string>;
+        };
+        dragging: {
+            value: boolean;
+        };
+        startDrag: (ev: PointerEvent, el: HTMLElement | null) => void;
+        dock: (side: 'left' | 'right') => void;
+        floatHere: (el: HTMLElement | null) => void;
+        setCollapsed: (v: boolean) => void;
+    };
+    title: string;
+    /** Room the docked panel leaves at the bottom, for a floating control bar. */
+    bottomClass?: string;
+    /** Tailwind width, matching the `width` given to the composable. */
+    widthClass?: string;
+    /** Labels, so the package carries no copy of its own. */
+    labels: {
+        dockLeft: string;
+        dockRight: string;
+        floatHere: string;
+        collapse: string;
+        expand: string;
+        placement: string;
+    };
+};
+declare var __VLS_5: {}, __VLS_67: {}, __VLS_69: {};
+type __VLS_Slots = {} & {
+    'pill-icon'?: (props: typeof __VLS_5) => any;
+} & {
+    default?: (props: typeof __VLS_67) => any;
+} & {
+    footer?: (props: typeof __VLS_69) => any;
+};
+declare const __VLS_component: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {
+    bottomClass: string;
+    widthClass: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: __VLS_WithSlots<typeof __VLS_component, __VLS_Slots>;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/composables/useFloatingPanel.d.ts

@@ -0,0 +1,69 @@
+import { type Ref } from 'vue';
+export type FloatingPanelDock = 'left' | 'right';
+export type FloatingPanelMode = 'docked-left' | 'docked-right' | 'floating';
+export interface FloatingPanelOptions {
+    /**
+     * Where this panel's placement is remembered. One key per panel — two panels
+     * sharing a key would drag each other around.
+     */
+    storageKey: string;
+    /** Which side it starts on, before anybody has moved it. */
+    initialMode?: FloatingPanelMode;
+    /** The panel's width, in px. Used to clamp it inside the canvas. */
+    width?: number;
+    /** Room to keep clear at the bottom, for a floating control bar. */
+    bottomClearance?: number;
+}
+/**
+ * A panel that can be docked to either side of a canvas, floated anywhere on
+ * it, or collapsed into a pill — and dragged between those states by its own
+ * header.
+ *
+ * Lifted from the integration studio's workflow editor, where this shape was
+ * worked out and where it has been in daily use: `usePaletteLayout`, with the
+ * storage key and the dimensions made arguments so a second editor can have
+ * its own panels rather than fighting over one remembered position.
+ *
+ * ## Why pointer events rather than HTML5 drag
+ *
+ * The panel's CONTENTS are draggable — the workflow editor drags nodes out of
+ * its palette onto the canvas, and the mail builder drags blocks. HTML5 drag
+ * on the shell would swallow those gestures. The header moves the panel with
+ * plain pointer events, so the two never compete: grab the bar, or grab a row,
+ * and each does the one thing.
+ *
+ * ## The magnet
+ *
+ * Coming within `DOCK_ZONE` of the left or right edge while dragging arms
+ * `dockPreview`, which the host renders as a ghost of the dock slot. Releasing
+ * inside the zone snaps into that dock; anywhere else leaves the panel where it
+ * was dropped. Docking is a state, not a position, so a docked panel keeps its
+ * side when the window resizes.
+ *
+ * Placement is persisted (guarded — private mode and quota must not throw) and
+ * clamped to the canvas on restore, because the window may have shrunk since.
+ */
+export declare function useFloatingPanel(canvasRef: Ref<HTMLElement | null>, options: FloatingPanelOptions): {
+    mode: Ref<FloatingPanelMode, FloatingPanelMode>;
+    collapsed: Ref<boolean, boolean>;
+    floating: Ref<{
+        x: number;
+        y: number;
+    }, {
+        x: number;
+        y: number;
+    } | {
+        x: number;
+        y: number;
+    }>;
+    floatingStyle: import("vue").ComputedRef<{
+        left: string;
+        top: string;
+    }>;
+    dragging: Ref<boolean, boolean>;
+    dockPreview: Ref<FloatingPanelDock | null, FloatingPanelDock | null>;
+    startDrag: (ev: PointerEvent, shellEl: HTMLElement | null) => void;
+    dock: (side: FloatingPanelDock) => void;
+    floatHere: (shellEl: HTMLElement | null) => void;
+    setCollapsed: (v: boolean) => void;
+};

package/dist/runtime/composables/useFloatingPanel.js

@@ -0,0 +1,112 @@
+import { computed, onBeforeUnmount, onMounted, ref } from "vue";
+const MARGIN = 12;
+const DOCK_ZONE = 48;
+function clampNum(v, lo, hi) {
+  return Math.min(hi, Math.max(lo, v));
+}
+export function useFloatingPanel(canvasRef, options) {
+  const width = options.width ?? 320;
+  const bottomClearance = options.bottomClearance ?? 64;
+  const mode = ref(options.initialMode ?? "docked-left");
+  const collapsed = ref(false);
+  const floating = ref({ x: MARGIN, y: MARGIN });
+  const dragging = ref(false);
+  const dockPreview = ref(null);
+  function persist() {
+    try {
+      const payload = { mode: mode.value, floating: floating.value, collapsed: collapsed.value };
+      localStorage.setItem(options.storageKey, JSON.stringify(payload));
+    } catch {
+    }
+  }
+  function restore() {
+    try {
+      const raw = localStorage.getItem(options.storageKey);
+      if (!raw) return;
+      const saved = JSON.parse(raw);
+      if (saved.mode === "docked-left" || saved.mode === "docked-right" || saved.mode === "floating") {
+        mode.value = saved.mode;
+      }
+      if (typeof saved.floating?.x === "number" && typeof saved.floating?.y === "number") {
+        floating.value = { x: saved.floating.x, y: saved.floating.y };
+      }
+      collapsed.value = saved.collapsed === true;
+      clampFloating();
+    } catch {
+    }
+  }
+  function clampFloating() {
+    const rect = canvasRef.value?.getBoundingClientRect();
+    if (!rect || rect.width === 0) return;
+    floating.value = {
+      x: clampNum(floating.value.x, MARGIN, Math.max(MARGIN, rect.width - width - MARGIN)),
+      y: clampNum(floating.value.y, MARGIN, Math.max(MARGIN, rect.height - bottomClearance - 160))
+    };
+  }
+  onMounted(restore);
+  let grabDX = 0;
+  let grabDY = 0;
+  let panelHeight = 0;
+  function startDrag(ev, shellEl) {
+    if (ev.button !== 0 || dragging.value) return;
+    if (ev.target?.closest("button")) return;
+    const canvas = canvasRef.value;
+    if (!canvas || !shellEl) return;
+    const cRect = canvas.getBoundingClientRect();
+    const pRect = shellEl.getBoundingClientRect();
+    floating.value = { x: pRect.left - cRect.left, y: pRect.top - cRect.top };
+    mode.value = "floating";
+    grabDX = ev.clientX - pRect.left;
+    grabDY = ev.clientY - pRect.top;
+    panelHeight = Math.min(pRect.height, window.innerHeight * 0.7);
+    dragging.value = true;
+    ev.preventDefault();
+    window.addEventListener("pointermove", onDragMove);
+    window.addEventListener("pointerup", onDragEnd);
+    window.addEventListener("pointercancel", onDragEnd);
+  }
+  function onDragMove(ev) {
+    const rect = canvasRef.value?.getBoundingClientRect();
+    if (!rect) return;
+    const x = clampNum(ev.clientX - rect.left - grabDX, MARGIN, Math.max(MARGIN, rect.width - width - MARGIN));
+    const y = clampNum(ev.clientY - rect.top - grabDY, MARGIN, Math.max(MARGIN, rect.height - bottomClearance - panelHeight));
+    floating.value = { x, y };
+    dockPreview.value = x <= DOCK_ZONE ? "left" : x + width >= rect.width - DOCK_ZONE ? "right" : null;
+  }
+  function stopListeners() {
+    window.removeEventListener("pointermove", onDragMove);
+    window.removeEventListener("pointerup", onDragEnd);
+    window.removeEventListener("pointercancel", onDragEnd);
+  }
+  function onDragEnd() {
+    if (dockPreview.value) mode.value = dockPreview.value === "left" ? "docked-left" : "docked-right";
+    dockPreview.value = null;
+    dragging.value = false;
+    stopListeners();
+    persist();
+  }
+  onBeforeUnmount(stopListeners);
+  function dock(side) {
+    mode.value = side === "left" ? "docked-left" : "docked-right";
+    persist();
+  }
+  function floatHere(shellEl) {
+    if (mode.value !== "floating") {
+      const cRect = canvasRef.value?.getBoundingClientRect();
+      const pRect = shellEl?.getBoundingClientRect();
+      if (cRect && pRect) floating.value = { x: pRect.left - cRect.left, y: pRect.top - cRect.top };
+      mode.value = "floating";
+      clampFloating();
+    }
+    persist();
+  }
+  function setCollapsed(v) {
+    collapsed.value = v;
+    persist();
+  }
+  const floatingStyle = computed(() => ({
+    left: `${floating.value.x}px`,
+    top: `${floating.value.y}px`
+  }));
+  return { mode, collapsed, floating, floatingStyle, dragging, dockPreview, startDrag, dock, floatHere, setCollapsed };
+}

package/dist/runtime/composables/useTalkbackChannels.d.ts

@@ -21,12 +21,27 @@ import type { MaybeRefOrGetter } from '@revenexx/talkback-js/vue';
  *    with the caller's scope — which is also what gives the delegate's own
  *    `onScopeDispose(release)` a scope to bind to.
  *
- * 3. **`channel` is actually reactive.** Up to and including
- *    `@revenexx/talkback-js@0.1.3`, `ChannelSubscription.channel` is
- *    `{ value: null }` cast to a `Ref` — `ref` is never imported, so `isRef()`
- *    is false and a template binding never updates. Fixed upstream in
- *    talkback-js#11 but unreleased; this wrapper can be simplified to a
- *    pass-through once that ships.
+ * 3. **An attach that cannot name a channel yet is retried, as long as what is
+ *    missing is reactive.** `useChannel` attaches EAGERLY and only then installs
+ *    the watch that would re-attach, and the eager call has no `try` around
+ *    `resolveName()` while the watch's source does. So a name the grammar rejects
+ *    at that moment — overwhelmingly a tenant that has not been loaded yet, since
+ *    it is positionally first in every channel name — throws straight out of the
+ *    composable, before anything exists that could try again. Swallowing that (as
+ *    this wrapper once did) turns "not yet" into "never": the subscription is lost
+ *    for the life of the tab while the socket connects perfectly well, which is
+ *    the shape realtime silently missing takes. The attach therefore runs inside
+ *    an effect, so the reads that got as far as throwing are tracked and the
+ *    attempt is repeated when one of them changes.
+ *
+ *    THE QUALIFIER IS LOAD-BEARING, and `useTalkbackUser` is where it bites:
+ *    `userChannel(tenant, '')` throws too, but the subject is a plain `let userId`
+ *    in `createPlatformTalkback` — cached from the last mint so it can answer
+ *    synchronously — so the tenant is the only tracked read and a subject that
+ *    fills in later re-runs nothing. That is not new (the throw was swallowed
+ *    before as well, and there was no channel either way), and a null token is the
+ *    ordinary state for up to fifteen seconds per `usePlatformTalkback`. Making
+ *    `userId` reactive is what would close it.
  *
  * With realtime off (`talkbackHost` empty) every one of these is a no-op that
  * reports a null channel, so a call site needs no `if (enabled)`.