@brftech/filex-core 0.39.0 → 0.39.1

package/src/components/OnboardingTour.vue

@@ -19,6 +19,7 @@
 import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue';
 import type { LocaleCode, ThemeMode } from '../types/ExplorerConfig';
 import { useLocale } from '../composables/useLocale';
+import { shortcutHint } from '../composables/useKeyboardShortcuts';
 
 const props = defineProps<{
   open: boolean;
@@ -34,6 +35,15 @@ const emit = defineEmits<{
 
 const { t } = useLocale(() => props.locale);
 
+/* The tour teaches two keys by name, and both are remappable. Read them
+ * from the registry so the sentence stays true for whoever is taking the
+ * tour — a walkthrough that names the wrong key is worse than one that
+ * names none. */
+const hintCombos = computed(() => ({
+  palette: shortcutHint('palette'),
+  help: shortcutHint('help'),
+}));
+
 // ------------------------------------------------------------------
 // Step definitions. `target` returns the element to spotlight (null =
 // centered card, e.g. the closing shortcuts step). Buttons without a
@@ -299,7 +309,7 @@ const themeClass = computed(() => `fe-ctx-backdrop--theme-${props.theme || 'auto
             {{ 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>
+          <p class="fe-tour__desc">{{ t(step.descKey, hintCombos) }}</p>
           <div class="fe-tour__dots" aria-hidden="true">
             <span
               v-for="(s, i) in activeSteps"

package/src/components/QuickLook.vue

@@ -18,10 +18,11 @@
  * input) are left alone. Esc is untouched — PreviewModal's own Modal
  * already closes on it.
  */
-import { onBeforeUnmount, watch } from 'vue';
+import { computed, onBeforeUnmount, watch } from 'vue';
 import type { FileNode } from '../types/FileNode';
 import type { LocaleCode } from '../types/ExplorerConfig';
 import { useLocale } from '../composables/useLocale';
+import { eventMatchesShortcut, shortcutHint } from '../composables/useKeyboardShortcuts';
 import PreviewModal from '../modals/PreviewModal.vue';
 
 const props = defineProps<{
@@ -61,16 +62,38 @@ function inFormControl(target: EventTarget | null): boolean {
   );
 }
 
+/**
+ * The peek's own arrows. These are NOT registry actions — they only
+ * mean anything while the overlay is up — so they are declared once
+ * here and the hint bar prints this same constant. Two copies of a key
+ * name is how a legend starts lying about the key it names.
+ */
+const NAV_KEYS = ['↑', '↓'] as const;
+
 function onKeydown(e: KeyboardEvent) {
   if (!props.open) return;
-  if (e.ctrlKey || e.metaKey || e.altKey) return;
   if (inFormControl(e.target)) return;
+
+  // ⚠ The registry first, and BEFORE the modifier bail-out: the user may
+  // have remapped quick-look onto a combo that carries Ctrl or Alt. The
+  // old version compared `e.key` to a hardcoded ' ' / 'Enter', so after a
+  // remap the peek opened on the new key and still closed on the old one
+  // — and the hint bar named the old one.
+  if (eventMatchesShortcut(e, 'quicklook')) {
+    e.preventDefault();
+    e.stopPropagation();
+    emit('close');
+    return;
+  }
+  if (eventMatchesShortcut(e, 'open')) {
+    e.preventDefault();
+    e.stopPropagation();
+    emit('open-full');
+    return;
+  }
+
+  if (e.ctrlKey || e.metaKey || e.altKey) return;
   switch (e.key) {
-    case ' ':
-      e.preventDefault();
-      e.stopPropagation();
-      emit('close');
-      break;
     case 'ArrowRight':
     case 'ArrowDown':
       e.preventDefault();
@@ -83,14 +106,23 @@ function onKeydown(e: KeyboardEvent) {
       e.stopPropagation();
       emit('nav', -1);
       break;
-    case 'Enter':
-      e.preventDefault();
-      e.stopPropagation();
-      emit('open-full');
-      break;
   }
 }
 
+/**
+ * The legend, read from the live registry. A segment whose action the
+ * user has unbound disappears rather than printing an empty key cap.
+ */
+const hintSegments = computed(() => {
+  const segs: Array<{ id: string; keys: string[]; label: string }> = [];
+  const close = shortcutHint('quicklook');
+  if (close) segs.push({ id: 'quicklook', keys: [close], label: t('quicklook.hint_close') });
+  segs.push({ id: 'nav', keys: [...NAV_KEYS], label: t('quicklook.hint_nav') });
+  const open = shortcutHint('open');
+  if (open) segs.push({ id: 'open', keys: [open], label: t('quicklook.hint_open') });
+  return segs;
+});
+
 watch(
   () => props.open,
   (open) => {
@@ -122,21 +154,37 @@ onBeforeUnmount(() => window.removeEventListener('keydown', onKeydown, true));
     :viewer-base-url="viewerBaseUrl"
     @close="emit('close')"
   />
-  <transition name="fe-toast">
-    <div
-      v-if="open"
-      class="fe fe-ql-hint"
-      :class="{
-        'fe--theme-light': theme === 'light',
-        'fe--theme-dark': theme === 'dark',
-      }"
-      aria-hidden="true"
-    >
-      <kbd class="fe-kbd">Space</kbd> {{ t('quicklook.hint_close') }}
-      <span class="fe-ql-hint__sep">·</span>
-      <kbd class="fe-kbd">↑</kbd><kbd class="fe-kbd">↓</kbd> {{ t('quicklook.hint_nav') }}
-      <span class="fe-ql-hint__sep">·</span>
-      <kbd class="fe-kbd">Enter</kbd> {{ t('quicklook.hint_open') }}
-    </div>
-  </transition>
+  <!--
+    Teleported under <body> for the same reason as ContextMenu and
+    OnboardingTour: the hint carries the `fe` root class (that is how it
+    reaches the `--fe-*` theme variables), so while it sits inside the
+    explorer tree ANY host rule that reaches `.fe` by descendant also
+    reaches the hint — and a host selector is always more specific than
+    our own single class. web/src/views/Explore.vue sizes the embedded
+    explorer with `.explore-host[data-v-…] .fe { height: 100% }`; that
+    stretched the hint pill to the full viewport height (issue #22).
+    Teleporting takes it out of every host container, so only the
+    package's own rules can reach it.
+  -->
+  <Teleport to="body">
+    <transition name="fe-toast">
+      <div
+        v-if="open"
+        class="fe fe-ql-hint"
+        :class="{
+          'fe--theme-light': theme === 'light',
+          'fe--theme-dark': theme === 'dark',
+        }"
+        aria-hidden="true"
+      >
+        <template v-for="(seg, i) in hintSegments" :key="seg.id">
+          <span v-if="i > 0" class="fe-ql-hint__sep">·</span>
+          <span class="fe-ql-hint__seg">
+            <kbd v-for="k in seg.keys" :key="k" class="fe-kbd">{{ k }}</kbd>
+            {{ seg.label }}
+          </span>
+        </template>
+      </div>
+    </transition>
+  </Teleport>
 </template>

package/src/components/Toolbar.vue

@@ -17,6 +17,7 @@ import type { LocaleCode, ThemeMode } from '../types/ExplorerConfig';
 import ContextMenu, { type ContextAction } from './ContextMenu.vue';
 import ViewSwitcher from './ViewSwitcher.vue';
 import { useLocale } from '../composables/useLocale';
+import { eventMatchesShortcut, shortcutHint } from '../composables/useKeyboardShortcuts';
 
 export type SelectionMode = 'none' | 'single-file' | 'single-dir' | 'multi';
 
@@ -381,10 +382,12 @@ const moreActions = computed<ContextAction[]>(() => {
  * what the hint says, and Ctrl+K from anywhere else still opens the palette
  * as it has since cila:c.
  */
-const macLike =
-  typeof navigator !== 'undefined' &&
-  /mac|iphone|ipad|ipod/i.test(navigator.platform || navigator.userAgent || '');
-const paletteCombo = computed(() => (macLike ? '⌘ K' : 'Ctrl K'));
+/* ⚠ Read from the registry, not written here. This chip used to print a
+ * hardcoded `⌘ K` / `Ctrl K`, which stopped being true the moment anyone
+ * remapped the palette in the shortcut settings — the chip then named a
+ * key that did nothing, on the one control whose whole job is to teach
+ * that key. */
+const paletteCombo = computed(() => shortcutHint('palette'));
 
 const drivePlaceholder = computed(() =>
   props.scopeLabel
@@ -396,7 +399,9 @@ const drivePlaceholder = computed(() =>
  *  keystrokes aimed at an input — which is correct, and it would otherwise
  *  make the hint on this very field a lie. */
 function onSearchKeydown(ev: KeyboardEvent) {
-  if ((ev.ctrlKey || ev.metaKey) && (ev.key === 'k' || ev.key === 'K')) {
+  // The registry decides, so the chip beside this field and the key that
+  // actually escalates stay the same key after a remap.
+  if (eventMatchesShortcut(ev, 'palette')) {
     ev.preventDefault();
     ev.stopPropagation();
     emit('open-palette', localSearch.value);

package/src/composables/useKeyboardShortcuts.ts

@@ -314,6 +314,59 @@ export function useShortcutList(): ComputedRef<ShortcutView[]> {
   );
 }
 
+// --------------------------------------------------------------------
+// Hint surfaces
+// --------------------------------------------------------------------
+
+/**
+ * Is this a Mac-style keyboard? Only affects how a combo is PRINTED —
+ * the canonical form folds Meta into Ctrl, so one saved combo works on
+ * every platform and only the label differs.
+ */
+export function isMacLike(): boolean {
+  return (
+    typeof navigator !== 'undefined' &&
+    /mac|iphone|ipad|ipod/i.test(navigator.platform || navigator.userAgent || '')
+  );
+}
+
+/** Canonical combo → what a human should see. '' stays ''. */
+export function comboLabel(combo: string): string {
+  if (!combo) return '';
+  return isMacLike() ? combo.replace(/\bCtrl\b/g, '⌘') : combo;
+}
+
+/**
+ * The one way a hint may name a key.
+ *
+ * ⚠ Never write a key into a hint by hand — not in a template, not in a
+ * locale string. Every combo in this registry is remappable, so a
+ * hardcoded "Ctrl+K" is true only until someone opens the shortcut
+ * settings, and then it is a label that tells the user to press a key
+ * that does nothing. Call this instead and interpolate the result;
+ * `web/tests/ui/shortcutHints.test.ts` fails the build on a literal.
+ *
+ * Returns '' when the action is unbound, so a caller can drop the whole
+ * segment rather than print an empty key cap.
+ */
+export function shortcutHint(id: string): string {
+  return comboLabel(effectiveCombo(id));
+}
+
+/**
+ * Does this event fire the given registry action? For overlays that
+ * handle their own keys (the quick-look peek) rather than going through
+ * the global binder — without this they keep answering to the DEFAULT
+ * key after the user has remapped the action.
+ */
+export function eventMatchesShortcut(e: KeyboardEvent, id: string): boolean {
+  const combo = effectiveCombo(id);
+  if (!combo) return false;
+  const fired = comboFromEvent(e);
+  if (fired === combo) return true;
+  return defOf(id)?.fixedCombos?.includes(fired ?? '') ?? false;
+}
+
 /**
  * @deprecated Legacy static cheat-sheet shape (pre-registry). Kept for
  * API compatibility; use `useShortcutList()` for the live, remap-aware

package/src/index.ts

@@ -139,6 +139,13 @@ export {
   resetAllShortcuts,
   findShortcutConflict,
   comboFromEvent,
+  /* Hint surfaces: the only sanctioned way to NAME a key on screen. A hint
+   * written by hand is true until the user remaps that action, and then the
+   * product is telling them to press something that does nothing. */
+  shortcutHint,
+  comboLabel,
+  eventMatchesShortcut,
+  isMacLike,
 } from './composables/useKeyboardShortcuts';
 export type {
   ShortcutActionDef,

package/src/locales/en.ts

@@ -366,7 +366,7 @@ export const en: Record<string, string> = {
     'Pick files with this button — or simply drag & drop them anywhere in the window.',
   'tour.step.search.title': 'Search',
   'tour.step.search.desc':
-    'This box searches the whole storage by name — separators and one typo are forgiven, so "invoice 2026" finds invoice_2026.pdf. Add tag:invoice to filter by tag. The Ctrl+K command palette also runs commands.',
+    'This box searches the whole storage by name — separators and one typo are forgiven, so "invoice 2026" finds invoice_2026.pdf. Add tag:invoice to filter by tag. The {palette} command palette also runs commands.',
   'tour.step.view.title': 'Switch views',
   'tour.step.view.desc':
     'Toggle between the list and grid layout; your choice is remembered.',
@@ -375,7 +375,7 @@ export const en: Record<string, string> = {
     'Right-click any file and use "Share / Permissions" to create a link with an optional PIN and expiry.',
   'tour.step.help.title': 'Shortcuts',
   'tour.step.help.desc':
-    'Press ? for the shortcut cheat-sheet and Ctrl+K for the command palette. Replay this tour any time via "Restart the tour" in the menu.',
+    'Press {help} for the shortcut cheat-sheet and {palette} for the command palette. Replay this tour any time via "Restart the tour" in the menu.',
   'error.hint': 'This may be a temporary network or server problem. Please try again.',
   'error.details': 'Technical details',
   'col.star': 'Star',

package/src/locales/tr.ts

@@ -366,7 +366,7 @@ export const tr: Record<string, string> = {
     'Bu düğmeyle dosya seçebilirsin; dosyaları doğrudan pencereye sürükleyip bırakmak da çalışır.',
   'tour.step.search.title': 'Arama',
   'tour.step.search.desc':
-    'Bu kutu deponun tamamında ada göre arar; ayraçları ve bir harflik yazım hatasını affeder, yani "fatura 2026" yazdığında fatura_2026.pdf gelir. tag:fatura yazarak etikete göre süzebilirsin. Ctrl+K komut paleti ayrıca komut da çalıştırır.',
+    'Bu kutu deponun tamamında ada göre arar; ayraçları ve bir harflik yazım hatasını affeder, yani "fatura 2026" yazdığında fatura_2026.pdf gelir. tag:fatura yazarak etikete göre süzebilirsin. {palette} komut paleti ayrıca komut da çalıştırır.',
   'tour.step.view.title': 'Görünümü değiştir',
   'tour.step.view.desc':
     'Liste ve ızgara görünümü arasında geçiş yapabilirsin; seçimin hatırlanır.',
@@ -375,7 +375,7 @@ export const tr: Record<string, string> = {
     'Bir dosyaya sağ tıklayıp "Paylaş / İzinler" ile bağlantı oluşturabilir, PIN ve son kullanma süresi ekleyebilirsin.',
   'tour.step.help.title': 'Kısayollar',
   'tour.step.help.desc':
-    '? tuşu kısayol kartını, Ctrl+K komut paletini açar. Bu turu menüdeki "Turu tekrar başlat" ile dilediğinde yeniden izleyebilirsin.',
+    '{help} tuşu kısayol kartını, {palette} komut paletini açar. Bu turu menüdeki "Turu tekrar başlat" ile dilediğinde yeniden izleyebilirsin.',
   'error.hint': 'Bağlantı ya da sunucu kaynaklı geçici bir sorun olabilir. Yeniden deneyin.',
   'error.details': 'Teknik ayrıntılar',
   'col.star': 'Yıldız',

package/src/styles/base.css

@@ -2622,8 +2622,15 @@ filex-explorer {
 /* Quick-look hint bar — floats above the PreviewModal backdrop (z 70).
  * Carries the `.fe` class for the theme-variable cascade, so the `.fe`
  * root layout defaults (column flex, min-height 420px, 100% height)
- * must be explicitly neutralised here. */
-.fe-ql-hint {
+ * must be explicitly neutralised here.
+ *
+ * Written as `.fe.fe-ql-hint` on purpose: a single class ties with the
+ * `.fe` root rule and would be decided by source order alone, which is
+ * not something a host embed can be trusted to preserve. The hint is
+ * also Teleported under <body> (QuickLook.vue) so a host container's
+ * own `.fe` override cannot reach it by descendant — issue #22, where
+ * the pill grew to the full viewport height inside the admin UI. */
+.fe.fe-ql-hint {
   position: fixed;
   left: 50%;
   bottom: 14px;
@@ -2653,6 +2660,13 @@ filex-explorer {
 .fe-ql-hint__sep {
   opacity: 0.5;
 }
+/* One key-cap group plus its label, kept together so the pill can only
+ * break between segments. */
+.fe-ql-hint__seg {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
 /* /wiring:c2 */
 /* =========================================================
  * wiring:c3 — Operations center (unified upload + ops-queue surface)