@brftech/filex-core 0.4.2 → 0.5.0

package/src/components/ListView.vue

@@ -12,6 +12,7 @@ import type { LocaleCode } from '../types/ExplorerConfig';
 import { useLocale } from '../composables/useLocale';
 import { fileIconSvg } from '../lib/fileIcons';
 import { matchedInContent, snippetSegments } from '../lib/snippet'; /* bul:s3 */
+import { applyDragGhost } from '../lib/dragGhost'; /* wiring:c4 */
 import StarButton from './StarButton.vue';
 
 const props = defineProps<{
@@ -71,18 +72,38 @@ function onRowCtx(n: FileNode, ev: MouseEvent) {
 }
 
 function onItemDragStart(n: FileNode, ev: DragEvent) {
+  /* wiring:c4 — custom ghost (name + multi-select count badge). Visual
+   * only; the payload/selection logic stays in FileExplorer. */
+  applyDragGhost(
+    ev,
+    nodeDisplayName(n),
+    props.selected.has(n.path) ? props.selected.size : 1,
+  );
   emit('item-drag-start', n, ev);
 }
 
+/* wiring:c4 — droptarget highlight: the folder row currently hovered by an
+ * internal drag gets `.is-droptarget`. Purely visual — the accept/deny
+ * decision below is untouched (files never preventDefault, so the browser
+ * shows the native no-drop cursor on invalid targets). */
+const dropTargetPath = ref<string | null>(null);
+
 function onItemDragOver(n: FileNode, ev: DragEvent) {
   if (n.type !== 'dir') return;
   if (!ev.dataTransfer?.types.includes('application/x-brf-files')) return;
   ev.preventDefault();
   ev.stopPropagation();
   if (ev.dataTransfer) ev.dataTransfer.dropEffect = 'move';
+  dropTargetPath.value = n.path; /* wiring:c4 */
+}
+
+/* wiring:c4 */
+function onItemDragLeave(n: FileNode) {
+  if (dropTargetPath.value === n.path) dropTargetPath.value = null;
 }
 
 function onItemDrop(n: FileNode, ev: DragEvent) {
+  dropTargetPath.value = null; /* wiring:c4 */
   if (n.type !== 'dir') return;
   if (!ev.dataTransfer?.types.includes('application/x-brf-files')) return;
   ev.preventDefault();
@@ -292,9 +313,17 @@ const segments = computed<Segment[]>(() => {
 </script>
 
 <template>
-  <div class="fe-list" :class="{ 'is-loading': loading, 'has-star-col': !!apiBase || apiBase === '' }">
+  <!-- wiring:c4 — grid semantics: container role + localized labels; rows
+       carry aria-selected below. Structure/layout untouched. -->
+  <div
+    class="fe-list"
+    :class="{ 'is-loading': loading, 'has-star-col': !!apiBase || apiBase === '' }"
+    role="grid"
+    :aria-label="t('list.aria')"
+    :aria-busy="loading ? 'true' : undefined"
+  >
     <div class="fe-list__head" role="row">
-      <div class="fe-list__col fe-list__col--star" role="columnheader" aria-label="Star"></div>
+      <div class="fe-list__col fe-list__col--star" role="columnheader" :aria-label="t('col.star') /* wiring:c4 */"></div>
       <div class="fe-list__col fe-list__col--name" role="columnheader" :aria-sort="ariaSort('name')">
         <button type="button" class="fe-list__sort" :title="t('col.sort')" @click="toggleSort('name')">
           {{ t('col.name') }}
@@ -326,21 +355,25 @@ const segments = computed<Segment[]>(() => {
           'is-dir': n.type === 'dir',
           'is-trash': n.trashed,
           'is-clipped': clipped?.has(n.path),
+          'is-droptarget': dropTargetPath === n.path /* wiring:c4 */,
         }"
         role="row"
         tabindex="0"
+        :aria-selected="isSelected(n) ? 'true' : 'false'"
+        :aria-label="nodeDisplayName(n) /* wiring:c4 */"
         draggable="true"
         @click="onRowClick(n, $event)"
         @dblclick="onRowDbl(n)"
         @contextmenu="onRowCtx(n, $event)"
         @dragstart="onItemDragStart(n, $event)"
         @dragover="onItemDragOver(n, $event)"
+        @dragleave="onItemDragLeave(n) /* wiring:c4 */"
         @drop="onItemDrop(n, $event)"
         @touchstart.passive="onTouchStart(n, $event)"
         @touchend="cancelPress"
         @touchmove="cancelPress"
       >
-        <div class="fe-list__col fe-list__col--star" @click.stop>
+        <div class="fe-list__col fe-list__col--star" role="gridcell" @click.stop>
           <StarButton
             v-if="typeof n.id === 'number' && n.type === 'file'"
             :starred="!!starredIds?.has(n.id)"
@@ -351,7 +384,7 @@ const segments = computed<Segment[]>(() => {
             @change="(val: boolean) => emit('star-change', n, val)"
           />
         </div>
-        <div class="fe-list__col fe-list__col--name">
+        <div class="fe-list__col fe-list__col--name" role="gridcell">
           <span v-if="specialEmojiFor(n)" class="fe-list__icon" aria-hidden="true">{{ specialEmojiFor(n) }}</span>
           <!-- eslint-disable-next-line vue/no-v-html — static markup from lib/fileIcons -->
           <span v-else class="fe-list__icon fe-list__icon--svg" aria-hidden="true" v-html="fileIconSvg(n)"></span>
@@ -375,10 +408,10 @@ const segments = computed<Segment[]>(() => {
             </span>
           </div>
         </div>
-        <div class="fe-list__col fe-list__col--size">
+        <div class="fe-list__col fe-list__col--size" role="gridcell">
           {{ formatSize(n.size) }}
         </div>
-        <div class="fe-list__col fe-list__col--mod">
+        <div class="fe-list__col fe-list__col--mod" role="gridcell">
           {{ displayDate(n.last_modified) }}
         </div>
       </div>

package/src/components/OnboardingTour.vue

@@ -0,0 +1,332 @@
+<script setup lang="ts">
+/**
+ * OnboardingTour — wiring:c4 first-use coach-mark tour.
+ *
+ * A dependency-free spotlight walkthrough: each step targets a live DOM
+ * element inside the explorer root (resolved lazily — steps whose target
+ * is missing are skipped, so confined embeds with hidden surfaces never
+ * show a dangling spotlight). Positioning is hand-rolled with
+ * getBoundingClientRect + fixed overlay; the spotlight is a rounded
+ * cutout drawn with a huge box-shadow.
+ *
+ * Teleported under <body> (same reason as ContextMenu: transformed embed
+ * ancestors break position:fixed) and re-uses the `.fe-ctx-backdrop--theme-*`
+ * classes so the CSS-variable theme cascade applies outside the `.fe` tree.
+ *
+ * Persistence (`filex.tourDone`) is the PARENT's job — the tour only
+ * emits `close`; FileExplorer decides when it counts as done.
+ */
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue';
+import type { LocaleCode, ThemeMode } from '../types/ExplorerConfig';
+import { useLocale } from '../composables/useLocale';
+
+const props = defineProps<{
+  open: boolean;
+  locale: LocaleCode;
+  /** Explorer root — targets are resolved inside it only. */
+  root: HTMLElement | null;
+  theme?: ThemeMode;
+}>();
+
+const emit = defineEmits<{
+  (e: 'close'): void;
+}>();
+
+const { t } = useLocale(() => props.locale);
+
+// ------------------------------------------------------------------
+// Step definitions. `target` returns the element to spotlight (null =
+// centered card, e.g. the closing shortcuts step). Buttons without a
+// stable class are found via their localized title attribute — the
+// toolbar gives every icon-only button a title from the same catalogue.
+// ------------------------------------------------------------------
+
+function byTitle(root: HTMLElement, label: string): HTMLElement | null {
+  const nodes = root.querySelectorAll<HTMLElement>('button[title]');
+  for (const el of Array.from(nodes)) {
+    if (el.getAttribute('title') === label) return el;
+  }
+  return null;
+}
+
+interface TourStep {
+  id: string;
+  titleKey: string;
+  descKey: string;
+  target: (root: HTMLElement) => HTMLElement | null;
+}
+
+const STEPS: TourStep[] = [
+  {
+    id: 'nav',
+    titleKey: 'tour.step.nav.title',
+    descKey: 'tour.step.nav.desc',
+    target: (r) => r.querySelector<HTMLElement>('.fe-breadcrumb'),
+  },
+  {
+    id: 'upload',
+    titleKey: 'tour.step.upload.title',
+    descKey: 'tour.step.upload.desc',
+    target: (r) =>
+      byTitle(r, t('toolbar.upload')) || r.querySelector<HTMLElement>('.fe-fab'),
+  },
+  {
+    id: 'search',
+    titleKey: 'tour.step.search.title',
+    descKey: 'tour.step.search.desc',
+    target: (r) =>
+      r.querySelector<HTMLElement>('.fe-search__input') ||
+      r.querySelector<HTMLElement>('.fe-toolbar__search-toggle'),
+  },
+  {
+    id: 'view',
+    titleKey: 'tour.step.view.title',
+    descKey: 'tour.step.view.desc',
+    target: (r) => r.querySelector<HTMLElement>('.fe-toolbar__view'),
+  },
+  {
+    id: 'share',
+    titleKey: 'tour.step.share.title',
+    descKey: 'tour.step.share.desc',
+    target: (r) => r.querySelector<HTMLElement>('.fe__body'),
+  },
+  {
+    id: 'help',
+    titleKey: 'tour.step.help.title',
+    descKey: 'tour.step.help.desc',
+    target: () => null,
+  },
+];
+
+// Steps re-resolved on every open so surfaces that appeared/disappeared
+// since mount (narrow-mode collapse, RBAC hiding upload…) are honored.
+const activeSteps = ref<TourStep[]>([]);
+const stepIdx = ref(0);
+
+const step = computed<TourStep | null>(() => activeSteps.value[stepIdx.value] ?? null);
+const total = computed(() => activeSteps.value.length);
+
+function resolveSteps() {
+  const r = props.root;
+  activeSteps.value = STEPS.filter((s) => {
+    if (s.id === 'help') return true; // centered card — no DOM dependency
+    if (!r) return false;
+    const el = s.target(r);
+    // Element must exist AND be laid out (visible) — a display:none
+    // toolbar section in narrow mode yields a 0×0 rect.
+    if (!el) return false;
+    const rect = el.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  });
+}
+
+// ------------------------------------------------------------------
+// Spotlight + card geometry
+// ------------------------------------------------------------------
+
+interface Rect {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+const spot = ref<Rect | null>(null);
+const cardStyle = ref<Record<string, string>>({});
+const cardEl = ref<HTMLElement | null>(null);
+
+const PAD = 6; // spotlight breathing room around the target
+const GAP = 12; // gap between spotlight and the card
+
+async function place() {
+  const s = step.value;
+  const r = props.root;
+  if (!s) return;
+  const el = r ? s.target(r) : null;
+  if (!el) {
+    spot.value = null; // centered card
+    cardStyle.value = {};
+    return;
+  }
+  const rect = el.getBoundingClientRect();
+  if (rect.width <= 0 && rect.height <= 0) {
+    spot.value = null;
+    cardStyle.value = {};
+    return;
+  }
+  spot.value = {
+    top: rect.top - PAD,
+    left: rect.left - PAD,
+    width: rect.width + PAD * 2,
+    height: rect.height + PAD * 2,
+  };
+  // Card: below the spotlight when there's room, above otherwise;
+  // clamped into the viewport horizontally.
+  await nextTick();
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+  const cw = Math.min(340, vw - 24);
+  const ch = cardEl.value?.offsetHeight ?? 160;
+  let top = rect.bottom + PAD + GAP;
+  if (top + ch > vh - 12) top = Math.max(12, rect.top - PAD - GAP - ch);
+  let left = rect.left + rect.width / 2 - cw / 2;
+  left = Math.min(Math.max(12, left), vw - cw - 12);
+  cardStyle.value = {
+    top: `${Math.round(top)}px`,
+    left: `${Math.round(left)}px`,
+    width: `${cw}px`,
+  };
+}
+
+function onViewportChange() {
+  if (props.open) void place();
+}
+
+// ------------------------------------------------------------------
+// Flow
+// ------------------------------------------------------------------
+
+function next() {
+  if (stepIdx.value >= total.value - 1) {
+    emit('close');
+    return;
+  }
+  stepIdx.value += 1;
+}
+
+function back() {
+  if (stepIdx.value > 0) stepIdx.value -= 1;
+}
+
+function skip() {
+  emit('close');
+}
+
+function onKey(e: KeyboardEvent) {
+  if (!props.open) return;
+  if (e.key === 'Escape') {
+    e.stopPropagation();
+    skip();
+  } else if (e.key === 'ArrowRight' || e.key === 'Enter') {
+    e.preventDefault();
+    next();
+  } else if (e.key === 'ArrowLeft') {
+    e.preventDefault();
+    back();
+  }
+}
+
+watch(
+  () => props.open,
+  async (v) => {
+    if (v) {
+      stepIdx.value = 0;
+      resolveSteps();
+      await nextTick();
+      await place();
+      cardEl.value?.focus();
+    }
+  },
+);
+
+watch(stepIdx, async () => {
+  await place();
+  cardEl.value?.focus();
+});
+
+onMounted(() => {
+  window.addEventListener('resize', onViewportChange);
+  window.addEventListener('scroll', onViewportChange, true);
+});
+onBeforeUnmount(() => {
+  window.removeEventListener('resize', onViewportChange);
+  window.removeEventListener('scroll', onViewportChange, true);
+});
+
+// Theme cascade outside `.fe` — same pattern as ContextMenu.
+const prefersDark = ref(false);
+let mq: MediaQueryList | undefined;
+function syncPrefersDark(e?: MediaQueryListEvent | MediaQueryList) {
+  prefersDark.value = !!(e && 'matches' in e && e.matches);
+}
+onMounted(() => {
+  if (typeof window === 'undefined') return;
+  mq = window.matchMedia('(prefers-color-scheme: dark)');
+  syncPrefersDark(mq);
+  mq.addEventListener?.('change', syncPrefersDark);
+});
+onBeforeUnmount(() => {
+  mq?.removeEventListener?.('change', syncPrefersDark);
+});
+const themeClass = computed(() => `fe-ctx-backdrop--theme-${props.theme || 'auto'}`);
+</script>
+
+<template>
+  <Teleport to="body">
+    <transition name="fe-tour">
+      <div
+        v-if="open && step"
+        class="fe-tour"
+        :class="themeClass"
+        :data-prefers-dark="prefersDark ? '1' : '0'"
+        role="dialog"
+        aria-modal="true"
+        :aria-label="t('tour.aria')"
+        @keydown="onKey"
+      >
+        <!-- Spotlight: rounded cutout via huge box-shadow. Centered steps
+             (no target) use a full-dim overlay instead. -->
+        <div
+          v-if="spot"
+          class="fe-tour__spot"
+          :style="{
+            top: spot.top + 'px',
+            left: spot.left + 'px',
+            width: spot.width + 'px',
+            height: spot.height + 'px',
+          }"
+          aria-hidden="true"
+        />
+        <div v-else class="fe-tour__dim" aria-hidden="true" />
+
+        <div
+          ref="cardEl"
+          class="fe-tour__card"
+          :class="{ 'fe-tour__card--center': !spot }"
+          :style="spot ? cardStyle : {}"
+          tabindex="-1"
+        >
+          <p class="fe-tour__progress" aria-hidden="true">
+            {{ t('tour.progress', { n: stepIdx + 1, m: total }) }}
+          </p>
+          <h3 class="fe-tour__title">{{ t(step.titleKey) }}</h3>
+          <p class="fe-tour__desc">{{ t(step.descKey) }}</p>
+          <div class="fe-tour__dots" aria-hidden="true">
+            <span
+              v-for="(s, i) in activeSteps"
+              :key="s.id"
+              class="fe-tour__dot"
+              :class="{ 'is-active': i === stepIdx }"
+            />
+          </div>
+          <div class="fe-tour__actions">
+            <button type="button" class="fe-btn fe-tour__skip" @click="skip">
+              {{ t('tour.skip') }}
+            </button>
+            <span class="fe-tour__actions-spacer" />
+            <button
+              v-if="stepIdx > 0"
+              type="button"
+              class="fe-btn"
+              @click="back"
+            >
+              {{ t('tour.back') }}
+            </button>
+            <button type="button" class="fe-btn fe-btn--primary" @click="next">
+              {{ stepIdx >= total - 1 ? t('tour.done') : t('tour.next') }}
+            </button>
+          </div>
+        </div>
+      </div>
+    </transition>
+  </Teleport>
+</template>