@brftech/filex-core 0.42.2 → 0.43.0

package/src/components/plugin/nodes/SurfacePeoplePicker.vue

@@ -0,0 +1,213 @@
+<script setup lang="ts">
+/**
+ * SurfacePeoplePicker — a plugin surface's `people-picker` node: who a
+ * document goes to. Chips for the people already chosen, one box to add
+ * the next.
+ *
+ * Internal users come from `GET /api/files/plugins/users?plugin=&q=`, which
+ * answers only for a plugin that holds `users:lookup`. A 403 (or a 404 from
+ * a server without the route) turns the lookup off for the life of the
+ * node and the box becomes plain e-mail entry — the contract's fallback,
+ * and the reason the box never says "no results" for a refusal.
+ *
+ * Free e-mail entry is offered when the plugin allows external people OR
+ * the lookup is off: with neither a way to name a user nor a way to type
+ * one, the node would be a wall.
+ */
+import { computed, onBeforeUnmount, ref, watch } from 'vue';
+import type { LocaleCode } from '../../../types/ExplorerConfig';
+import type { FileApi } from '../../../composables/useFileApi';
+import type { PluginPerson } from '../../../types/Plugins';
+import { useLocale } from '../../../composables/useLocale';
+import { personName } from '../../../lib/personName';
+import { looksLikeEmail } from '../../../lib/surfaceValues';
+import { isListSeparatorKey } from '../../../lib/listInput';
+
+const props = defineProps<{
+  id: string;
+  modelValue: PluginPerson[];
+  multi?: boolean;
+  allowExternal?: boolean;
+  /** Absent: no lookup at all — free e-mail entry only. */
+  api?: Pick<FileApi, 'pluginUsers'>;
+  /** The plugin the lookup is asked for. */
+  plugin?: string;
+  locale: LocaleCode;
+  disabled?: boolean;
+  invalid?: boolean;
+}>();
+
+const emit = defineEmits<{
+  (e: 'update:modelValue', v: PluginPerson[]): void;
+}>();
+
+const { t } = useLocale(() => props.locale);
+
+const query = ref('');
+const suggestions = ref<PluginPerson[]>([]);
+const showSuggest = ref(false);
+/** The server refused (403) or has no route (404): free e-mail entry only. */
+const lookupOff = ref(!props.api || !props.plugin);
+const notice = ref('');
+let timer: ReturnType<typeof setTimeout> | null = null;
+let lastQuery = 0;
+
+const people = computed(() => props.modelValue ?? []);
+const freeEntry = computed(() => props.allowExternal === true || lookupOff.value);
+const full = computed(() => props.multi !== true && people.value.length >= 1);
+
+/* One rule for naming a person (lib/personName). */
+function personLabel(p: PluginPerson): string {
+  return personName({ name: p.name, email: p.email });
+}
+
+function add(p: PluginPerson) {
+  const email = String(p.email ?? '').trim().toLowerCase();
+  if (!email) return;
+  const rest = props.multi === true ? people.value.filter((x) => x.email.toLowerCase() !== email) : [];
+  emit('update:modelValue', [...rest, { ...p, email }]);
+  query.value = '';
+  suggestions.value = [];
+  showSuggest.value = false;
+  notice.value = '';
+}
+
+function remove(email: string) {
+  emit('update:modelValue', people.value.filter((x) => x.email !== email));
+}
+
+function onInput() {
+  notice.value = '';
+  const q = query.value.trim();
+  if (timer) clearTimeout(timer);
+  if (!q || lookupOff.value) {
+    suggestions.value = [];
+    showSuggest.value = false;
+    return;
+  }
+  timer = setTimeout(() => void search(q), 180);
+}
+
+async function search(q: string) {
+  if (!props.api || !props.plugin || lookupOff.value) return;
+  const mine = ++lastQuery;
+  try {
+    const r = await props.api.pluginUsers(props.plugin, q);
+    if (mine !== lastQuery) return;
+    suggestions.value = (r.users ?? []).filter((u) => u && typeof u.email === 'string');
+    showSuggest.value = suggestions.value.length > 0;
+  } catch (e) {
+    if (mine !== lastQuery) return;
+    const status = (e as { status?: number })?.status;
+    if (status === 403 || status === 404) lookupOff.value = true;
+    suggestions.value = [];
+    showSuggest.value = false;
+  }
+}
+
+/** Enter / comma: the typed address, when free entry is allowed. */
+function commit() {
+  const q = query.value.trim();
+  if (!q) return;
+  if (!freeEntry.value) {
+    notice.value = t('plugin.people.external_off');
+    return;
+  }
+  if (!looksLikeEmail(q)) {
+    notice.value = t('plugin.people.invalid_email');
+    return;
+  }
+  add({ email: q });
+}
+
+function onKeydown(ev: KeyboardEvent) {
+  // ⚠ "،" / "，" commit too (lib/listInput — an Arabic or CJK keyboard).
+  if (ev.key === 'Enter' || isListSeparatorKey(ev.key)) {
+    ev.preventDefault();
+    commit();
+  } else if (ev.key === 'Backspace' && query.value === '' && people.value.length) {
+    remove(people.value[people.value.length - 1].email);
+  } else if (ev.key === 'Escape') {
+    showSuggest.value = false;
+  }
+}
+
+function onBlur() {
+  // Let a mousedown on a suggestion land first.
+  setTimeout(() => {
+    showSuggest.value = false;
+  }, 120);
+}
+
+watch(
+  () => [props.api, props.plugin] as const,
+  ([api, plugin]) => {
+    if (api && plugin) lookupOff.value = false;
+  },
+);
+
+onBeforeUnmount(() => {
+  if (timer) clearTimeout(timer);
+});
+</script>
+
+<template>
+  <div class="fe-speople" :class="{ 'is-invalid': invalid }" data-testid="surface-people">
+    <ul v-if="people.length" class="fe-speople__chips" data-testid="surface-people-chips">
+      <li v-for="p in people" :key="p.email" class="fe-speople__chip" :title="p.email">
+        <span class="fe-speople__av" aria-hidden="true">{{ personLabel(p).charAt(0).toUpperCase() }}</span>
+        <span class="fe-speople__name">{{ personLabel(p) }}</span>
+        <button
+          type="button"
+          class="fe-speople__remove"
+          :disabled="disabled"
+          :title="t('plugin.people.remove', { name: personLabel(p) })"
+          :aria-label="t('plugin.people.remove', { name: personLabel(p) })"
+          :data-testid="`surface-people-remove-${p.email}`"
+          @click="remove(p.email)"
+        >
+          <svg class="fe-ficon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true" focusable="false">
+            <path d="M6 6l12 12M18 6L6 18" />
+          </svg>
+        </button>
+      </li>
+    </ul>
+    <div v-if="!full" class="fe-speople__addwrap">
+      <input
+        v-model="query"
+        class="fe-cfield__input fe-speople__input"
+        type="email"
+        autocomplete="off"
+        spellcheck="false"
+        :placeholder="lookupOff ? t('plugin.people.placeholder_email') : t('plugin.people.placeholder')"
+        :disabled="disabled"
+        :aria-invalid="invalid ? 'true' : undefined"
+        data-testid="surface-people-input"
+        @input="onInput"
+        @keydown="onKeydown"
+        @focus="onInput"
+        @blur="onBlur"
+      />
+      <button
+        v-if="freeEntry"
+        type="button"
+        class="fe-btn fe-btn--sm"
+        :disabled="disabled || !query.trim()"
+        data-testid="surface-people-add"
+        @click="commit"
+      >
+        {{ t('plugin.people.add') }}
+      </button>
+      <ul v-if="showSuggest" class="fe-share__suggest fe-speople__suggest" data-testid="surface-people-suggest">
+        <li v-for="u in suggestions" :key="u.user_id ?? u.email" @mousedown.prevent="add(u)">
+          <span class="fe-share__av fe-share__av--sm">{{ personLabel(u).charAt(0).toUpperCase() }}</span>
+          <span class="fe-share__suggesttxt">
+            <span class="fe-share__suggestname">{{ personLabel(u) }}</span>
+            <span class="fe-share__suggestmeta">{{ u.email }}</span>
+          </span>
+        </li>
+      </ul>
+    </div>
+    <p v-if="notice" class="fe-surface__error" role="alert">{{ notice }}</p>
+  </div>
+</template>

package/src/components/plugin/nodes/SurfacePinInput.vue

@@ -0,0 +1,57 @@
+<script setup lang="ts">
+/**
+ * SurfacePinInput — a plugin surface's `pin-input` node: a short code, 4..8
+ * characters, into `data.values[id]`. One input with the browser's one-time
+ * code affordances rather than N boxes: paste works, screen readers read one
+ * field, and the length is enforced by the same line that draws it.
+ */
+import { computed } from 'vue';
+import type { LocaleCode } from '../../../types/ExplorerConfig';
+import { useLocale } from '../../../composables/useLocale';
+import { pinLength } from '../../../lib/surfaceValues';
+
+const props = defineProps<{
+  id: string;
+  length?: number | unknown;
+  modelValue: string;
+  locale: LocaleCode;
+  disabled?: boolean;
+  invalid?: boolean;
+}>();
+
+const emit = defineEmits<{
+  (e: 'update:modelValue', v: string): void;
+}>();
+
+const { t } = useLocale(() => props.locale);
+
+const len = computed(() => pinLength(props.length));
+
+function onInput(ev: Event) {
+  const raw = (ev.target as HTMLInputElement).value.replace(/\s+/g, '').slice(0, len.value);
+  (ev.target as HTMLInputElement).value = raw;
+  emit('update:modelValue', raw);
+}
+</script>
+
+<template>
+  <div class="fe-spin" data-testid="surface-pin">
+    <label class="fe-cfield__label" :for="`fe-spin-${id}`">{{ t('plugin.pin.label') }}</label>
+    <input
+      :id="`fe-spin-${id}`"
+      class="fe-cfield__input fe-cfield__input--mono fe-spin__input"
+      :class="{ 'is-invalid': invalid }"
+      type="text"
+      inputmode="numeric"
+      autocomplete="one-time-code"
+      spellcheck="false"
+      :maxlength="len"
+      :size="len"
+      :value="modelValue"
+      :disabled="disabled"
+      :aria-invalid="invalid ? 'true' : undefined"
+      :style="{ '--spin-len': len }"
+      @input="onInput"
+    />
+  </div>
+</template>

package/src/components/plugin/nodes/SurfacePreview.vue

@@ -0,0 +1,119 @@
+<script setup lang="ts">
+/**
+ * SurfacePreview — a plugin surface's `preview` node: the explorer's own
+ * look at a storage file. The bytes come through `api.fetchBlob`, the same
+ * authenticated preview fetch every rich viewer uses (bearer / CSRF /
+ * credentials mode all honoured), so an embed on another origin sees the
+ * picture too. Pictures, video and audio are shown as themselves; anything
+ * else gets the listing's own type tile and the name.
+ *
+ * ⚠ No `<img src="/api/…">` for a PATH: a plain URL cannot carry the auth
+ * header and resolves against the HOST page's origin in an embed (see
+ * useThumbs). A public page's exposed copy (`ref`, M3) is the exception by
+ * design: there is no auth header, the PIN cookie rides with the same-origin
+ * URL the host's `fileUrl` resolver hands out, and the browser's own
+ * viewer draws it (`<img>` for a picture, `<embed>` for a PDF or anything
+ * else) — so the page never buffers a document in memory.
+ */
+import { computed, onBeforeUnmount, ref, watch } from 'vue';
+import type { LocaleCode } from '../../../types/ExplorerConfig';
+import type { FileApi } from '../../../composables/useFileApi';
+import type { FileRefResolver } from '../../../types/Plugins';
+import { useLocale } from '../../../composables/useLocale';
+import { labelOfWire } from '../../../lib/destinationTree';
+import { fileIconTile } from '../../../lib/fileIcons';
+
+const props = defineProps<{
+  /** Adapter-qualified path of a storage file. */
+  path: string;
+  /** A public page's exposed copy (`pub:N`), shown from `fileUrl(ref)`. */
+  fileRef?: string;
+  fileUrl?: FileRefResolver;
+  locale: LocaleCode;
+  /** Absent: the node says the preview is unavailable. */
+  api?: Pick<FileApi, 'fetchBlob'>;
+}>();
+
+const { t } = useLocale(() => props.locale);
+
+const url = ref<string | null>(null);
+const mime = ref('');
+const state = ref<'loading' | 'ok' | 'error'>('loading');
+let seq = 0;
+
+/** The exposed copy, when the node names one and the host can resolve it. */
+const exposed = computed(() => (props.fileRef && props.fileUrl ? props.fileUrl(props.fileRef) : null));
+
+const name = computed(() => exposed.value?.name || labelOfWire(props.path, '') || props.path || props.fileRef || '');
+const kind = computed<'image' | 'video' | 'audio' | 'other'>(() => {
+  const m = mime.value;
+  if (m.startsWith('image/')) return 'image';
+  if (m.startsWith('video/')) return 'video';
+  if (m.startsWith('audio/')) return 'audio';
+  return 'other';
+});
+const tile = computed(() => fileIconTile({ type: 'file', basename: name.value }));
+
+function release() {
+  // Only a blob URL this node minted is ours to revoke; an exposed copy's
+  // URL is the server's.
+  if (url.value && url.value.startsWith('blob:')) URL.revokeObjectURL(url.value);
+  url.value = null;
+}
+
+async function load() {
+  const mine = ++seq;
+  release();
+  mime.value = '';
+  if (props.fileRef) {
+    if (!exposed.value) {
+      state.value = 'error';
+      return;
+    }
+    url.value = exposed.value.url;
+    mime.value = exposed.value.mime || '';
+    state.value = 'ok';
+    return;
+  }
+  if (!props.api || !props.path) {
+    state.value = 'error';
+    return;
+  }
+  state.value = 'loading';
+  try {
+    const r = await props.api.fetchBlob(props.path);
+    if (mine !== seq) {
+      URL.revokeObjectURL(r.url);
+      return;
+    }
+    url.value = r.url;
+    mime.value = r.mime || '';
+    state.value = 'ok';
+  } catch {
+    if (mine !== seq) return;
+    state.value = 'error';
+  }
+}
+
+watch([() => props.path, () => props.fileRef], () => void load(), { immediate: true });
+onBeforeUnmount(() => {
+  seq++;
+  release();
+});
+</script>
+
+<template>
+  <figure class="fe-spreview" data-testid="surface-preview" :data-state="state">
+    <p v-if="state === 'loading'" class="fe-surface__text fe-surface__text--muted">{{ t('plugin.view.loading') }}</p>
+    <p v-else-if="state === 'error'" class="fe-surface__text fe-surface__text--muted">{{ t('plugin.view.preview_failed') }}</p>
+    <template v-else>
+      <img v-if="kind === 'image' && url" class="fe-spreview__media" :src="url" :alt="name" />
+      <video v-else-if="kind === 'video' && url" class="fe-spreview__media" :src="url" controls preload="metadata"></video>
+      <audio v-else-if="kind === 'audio' && url" class="fe-spreview__audio" :src="url" controls preload="metadata"></audio>
+      <embed v-else-if="fileRef && url" class="fe-spreview__media fe-spreview__embed" :src="url" :type="mime || undefined" />
+      <!-- eslint-disable-next-line vue/no-v-html -- static markup from lib/fileIcons -->
+      <span v-else class="fe-spreview__tile" aria-hidden="true" v-html="tile"></span>
+    </template>
+    <figcaption class="fe-spreview__name" :title="path">{{ name }}</figcaption>
+  </figure>
+</template>

package/src/components/plugin/nodes/SurfaceProgress.vue

@@ -0,0 +1,48 @@
+<script setup lang="ts">
+/**
+ * SurfaceProgress — a plugin surface's `progress` node. `value` 0..100, or
+ * null for "busy, no idea how long" (drawn as a moving bar).
+ */
+import { computed } from 'vue';
+import type { LocaleCode } from '../../../types/ExplorerConfig';
+import type { PluginText } from '../../../types/Plugins';
+import { useLocale } from '../../../composables/useLocale';
+import { appTextOr } from '../../../lib/pluginLabel';
+
+const props = defineProps<{
+  value: number | null | undefined;
+  label?: PluginText | string;
+  locale: LocaleCode;
+}>();
+
+const { t } = useLocale(() => props.locale);
+
+const pct = computed<number | null>(() => {
+  const v = props.value;
+  if (v === null || v === undefined || !Number.isFinite(Number(v))) return null;
+  return Math.min(100, Math.max(0, Math.round(Number(v))));
+});
+
+/* ⚠ See `appTextOr`: the app's line for this reader, then filex's own. */
+const text = computed(() => appTextOr(props.label, props.locale, () => t('plugin.view.busy')));
+</script>
+
+<template>
+  <div class="fe-sprogress" data-testid="surface-progress">
+    <div class="fe-sprogress__head">
+      <span class="fe-sprogress__label">{{ text }}</span>
+      <span v-if="pct !== null" class="fe-sprogress__pct">{{ pct }}%</span>
+    </div>
+    <div
+      class="fe-sprogress__track"
+      :class="{ 'is-indeterminate': pct === null }"
+      role="progressbar"
+      :aria-label="text"
+      aria-valuemin="0"
+      aria-valuemax="100"
+      :aria-valuenow="pct === null ? undefined : pct"
+    >
+      <div class="fe-sprogress__bar" :style="pct === null ? undefined : { width: `${pct}%` }"></div>
+    </div>
+  </div>
+</template>