@brftech/filex-core 0.42.1 → 0.43.0

package/src/lib/pdfFieldsGeom.ts

@@ -0,0 +1,203 @@
+/**
+ * pdfFieldsGeom — where a `pdf-fields` box is, as pure arithmetic.
+ *
+ * A field's place is stored as FRACTIONS of the page's rendered viewport
+ * (0..1, origin top-left, CropBox and /Rotate already applied by pdf.js's
+ * viewport), so it survives any zoom and any screen. Three conversions are
+ * needed around that and they all live here, DOM-free:
+ *
+ *   fraction ↔ pixel   the drag on screen (a page drawn `size` CSS px wide)
+ *   fraction ↔ PDF     the rectangle in PDF user space (points, origin
+ *                      bottom-left of the UNROTATED page) that a stamping
+ *                      plugin needs, for /Rotate 0, 90, 180 and 270
+ *
+ * The rotation maps are the ones pdf.js's `PageViewport` applies: 90 is the
+ * page turned clockwise on screen, so the unrotated top-left corner lands at
+ * the rendered top-right; 270 turns it counter-clockwise.
+ */
+
+/** A box as fractions of the rendered page (0..1, origin top-left). */
+export interface FracRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** A box in CSS pixels on a drawn page. */
+export interface PixelRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/** A box in PDF user space: points, origin bottom-left of the unrotated page. */
+export interface PdfRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** The rendered viewport at scale 1: its size after rotation, and that rotation. */
+export interface PageBox {
+  width: number;
+  height: number;
+  rotation: number;
+}
+
+export type Rotation = 0 | 90 | 180 | 270;
+
+/** Any degree count as one of the four the PDF spec allows. */
+export function normRotation(r: number | undefined | null): Rotation {
+  const n = Number(r);
+  if (!Number.isFinite(n)) return 0;
+  const m = ((Math.round(n / 90) * 90) % 360 + 360) % 360;
+  return m as Rotation;
+}
+
+/** The smallest box the editor lets a field shrink to (fractions). */
+export const MIN_FIELD_FRAC = { w: 0.02, h: 0.01 };
+
+const clamp01 = (v: number) => Math.min(1, Math.max(0, v));
+
+/** Inside the page, at least the minimum size, no NaN. */
+export function clampFrac(r: FracRect): FracRect {
+  const w = Math.min(1, Math.max(MIN_FIELD_FRAC.w, Number(r.w) || 0));
+  const h = Math.min(1, Math.max(MIN_FIELD_FRAC.h, Number(r.h) || 0));
+  const x = Math.min(1 - w, clamp01(Number(r.x) || 0));
+  const y = Math.min(1 - h, clamp01(Number(r.y) || 0));
+  return { x, y, w, h };
+}
+
+/** A box drawn between two points (any corner order), as fractions. */
+export function rectFromPoints(a: { x: number; y: number }, b: { x: number; y: number }): FracRect {
+  return clampFrac({
+    x: Math.min(a.x, b.x),
+    y: Math.min(a.y, b.y),
+    w: Math.abs(a.x - b.x),
+    h: Math.abs(a.y - b.y),
+  });
+}
+
+export function fracToPixel(r: FracRect, size: { width: number; height: number }): PixelRect {
+  return {
+    left: r.x * size.width,
+    top: r.y * size.height,
+    width: r.w * size.width,
+    height: r.h * size.height,
+  };
+}
+
+export function pixelToFrac(px: PixelRect, size: { width: number; height: number }): FracRect {
+  const W = size.width || 1;
+  const H = size.height || 1;
+  return { x: px.left / W, y: px.top / H, w: px.width / W, h: px.height / H };
+}
+
+/** A pointer position on a drawn page (CSS px from its top-left) as fractions. */
+export function pointToFrac(p: { x: number; y: number }, size: { width: number; height: number }): { x: number; y: number } {
+  return { x: clamp01(p.x / (size.width || 1)), y: clamp01(p.y / (size.height || 1)) };
+}
+
+/** The unrotated page's size in points, from the rendered viewport. */
+export function unrotatedSize(page: PageBox): { width: number; height: number } {
+  const rot = normRotation(page.rotation);
+  return rot === 90 || rot === 270 ? { width: page.height, height: page.width } : { width: page.width, height: page.height };
+}
+
+/** A rendered point (px, origin top-left) → the unrotated page's top-left system (points). */
+function renderedToPage(X: number, Y: number, page: PageBox): { x: number; y: number } {
+  const rot = normRotation(page.rotation);
+  const W = page.width;
+  const H = page.height;
+  switch (rot) {
+    case 90:
+      return { x: Y, y: W - X };
+    case 180:
+      return { x: W - X, y: H - Y };
+    case 270:
+      return { x: H - Y, y: X };
+    default:
+      return { x: X, y: Y };
+  }
+}
+
+/** Inverse of `renderedToPage`. */
+function pageToRendered(x: number, y: number, page: PageBox): { X: number; Y: number } {
+  const rot = normRotation(page.rotation);
+  const W = page.width;
+  const H = page.height;
+  switch (rot) {
+    case 90:
+      return { X: W - y, Y: x };
+    case 180:
+      return { X: W - x, Y: H - y };
+    case 270:
+      return { X: y, Y: H - x };
+    default:
+      return { X: x, Y: y };
+  }
+}
+
+/** Fractions of the rendered page → PDF user-space rectangle (points, origin bottom-left, unrotated). */
+export function fracToPdf(r: FracRect, page: PageBox): PdfRect {
+  const a = renderedToPage(r.x * page.width, r.y * page.height, page);
+  const b = renderedToPage((r.x + r.w) * page.width, (r.y + r.h) * page.height, page);
+  const { height: ph } = unrotatedSize(page);
+  const left = Math.min(a.x, b.x);
+  const right = Math.max(a.x, b.x);
+  const top = Math.min(a.y, b.y);
+  const bottom = Math.max(a.y, b.y);
+  return round({ x: left, y: ph - bottom, w: right - left, h: bottom - top });
+}
+
+/** PDF user-space rectangle → fractions of the rendered page. */
+export function pdfToFrac(r: PdfRect, page: PageBox): FracRect {
+  const { height: ph } = unrotatedSize(page);
+  const topLeft = { x: r.x, y: ph - (r.y + r.h) };
+  const bottomRight = { x: r.x + r.w, y: ph - r.y };
+  const a = pageToRendered(topLeft.x, topLeft.y, page);
+  const b = pageToRendered(bottomRight.x, bottomRight.y, page);
+  const W = page.width || 1;
+  const H = page.height || 1;
+  return round({
+    x: Math.min(a.X, b.X) / W,
+    y: Math.min(a.Y, b.Y) / H,
+    w: Math.abs(a.X - b.X) / W,
+    h: Math.abs(a.Y - b.Y) / H,
+  });
+}
+
+function round<T extends Record<string, number>>(o: T): T {
+  const out: Record<string, number> = {};
+  for (const [k, v] of Object.entries(o)) out[k] = Math.round(v * 1e6) / 1e6;
+  return out as T;
+}
+
+/**
+ * v3 §3.2 — the width to draw a page at so the WHOLE page fits the box.
+ *
+ * ⚠⚠ The complaint that started the round: a signature page you had to
+ * scroll in two directions. The document was fitted to the column's WIDTH, so
+ * a portrait page in a landscape window ran off the bottom — the boxes were
+ * then found by hunting rather than by reading. Fitting means whichever of
+ * the two constraints binds.
+ *
+ * `gap` is the breathing room around the page (the scroll box's padding),
+ * taken off the HEIGHT: a page that touches the toolbar reads as clipped.
+ * A box with no height yet (before layout) falls back to the width, which is
+ * the old behaviour and is corrected on the first resize observation.
+ */
+export function fitPageWidth(
+  box: { width: number; height: number },
+  page: { width: number; height: number },
+  gap = 16,
+): number {
+  const w = Math.max(0, box.width);
+  const h = Math.max(0, box.height) - gap;
+  if (!page.width || !page.height || h <= 0) return w;
+  const byHeight = (h * page.width) / page.height;
+  return Math.max(120, Math.min(w, byHeight));
+}

package/src/lib/pdfjsLoader.ts

@@ -0,0 +1,51 @@
+/**
+ * pdfjsLoader — the ONE way this package brings pdf.js in.
+ *
+ * `pdfjs-dist` is ~600 KB and an optional peer, so it is imported lazily and
+ * its absence is an answer (`null`), not an exception. The worker script is
+ * a separate file the browser fetches: the host may point at its own copy
+ * (`pdfWorkerUrl` in the explorer config) and otherwise the pinned version
+ * is taken from jsDelivr. `viewers/PdfViewer.vue` and the sign track's
+ * `pdf-fields` node both open documents through here, so the legacy build,
+ * the worker rule and the fallback cannot drift between them.
+ */
+
+/** The subset of the library the callers use; `any` on purpose — pdf.js ships no stable types for the legacy build. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type PdfjsLib = any;
+
+let cached: Promise<PdfjsLib | null> | null = null;
+
+/** The worker URL for a pdf.js version when the host names none. */
+export function defaultPdfWorkerUrl(version: string): string {
+  return `https://cdn.jsdelivr.net/npm/pdfjs-dist@${version}/legacy/build/pdf.worker.min.mjs`;
+}
+
+/**
+ * The library, or `null` when it cannot be loaded (not installed, blocked).
+ * The first caller's `workerUrl` wins; pdf.js holds one global worker path.
+ */
+export function loadPdfjs(workerUrl?: string | null): Promise<PdfjsLib | null> {
+  if (!cached) {
+    cached = (async () => {
+      try {
+        // The legacy build: broader browser support and a classic worker
+        // bootstrap (no module-worker requirement).
+        const mod = await import(/* @vite-ignore */ 'pdfjs-dist/legacy/build/pdf');
+        const lib = mod.default ?? mod;
+        if (lib.GlobalWorkerOptions && !lib.GlobalWorkerOptions.workerSrc) {
+          lib.GlobalWorkerOptions.workerSrc = workerUrl || defaultPdfWorkerUrl(lib.version || '5.7.284');
+        }
+        return lib;
+      } catch {
+        return null;
+      }
+    })();
+  }
+  return cached;
+}
+
+/** Tests only: forget the cached import so a mocked module is picked up. */
+export function resetPdfjsLoader(): void {
+  cached = null;
+}

package/src/lib/personName.ts

@@ -0,0 +1,47 @@
+/**
+ * personName — how filex names a person on screen. ONE rule, every surface.
+ *
+ * ⚠⚠ QA, 2026-09-21: one administrator was "admin2" in the explorer's Owner
+ * column, "admin@local" in notifications, the permissions panel and the admin
+ * tables, and a full name on signatures. Each place had its own chain —
+ * display name → username → e-mail (the Owner column, on the server), display
+ * name → e-mail (the share dialog, the details panel, the admin header),
+ * display name → e-mail local part (the presence strip). One chain now:
+ *
+ *   the name the server already worked out (`name` — a row's `owner_name`,
+ *   `user_name`, `creator_name`: model.PersonLabel on the server, the same
+ *   rule) → the display name → the username → the e-mail address.
+ *
+ * The server's twin is `model.PersonLabel` (backend/internal/model/user.go);
+ * web/tests/lib/personName.test.ts and the Go test hold both to the same
+ * cases. docs/CONTRIBUTING.md → "A person is named one way". The e-mail is a
+ * second line or a tooltip where it helps — never the name while a name exists.
+ */
+export interface PersonLike {
+  /** A label the server already resolved by the same rule. */
+  name?: string | null;
+  display_name?: string | null;
+  username?: string | null;
+  email?: string | null;
+}
+
+export function personName(p: PersonLike | null | undefined): string {
+  if (!p) return '';
+  for (const v of [p.name, p.display_name, p.username, p.email]) {
+    const s = typeof v === 'string' ? v.trim() : '';
+    if (s) return s;
+  }
+  return '';
+}
+
+/**
+ * The letter for a person's avatar circle: the first character of their name
+ * — a whole character (an emoji or an astral letter is a surrogate PAIR, and
+ * one half of it prints as �), upper-cased in the viewer's language (Turkish
+ * `i` → `İ`, never `I`). '' when there is no name; the caller draws a glyph.
+ */
+export function personInitial(p: PersonLike | null | undefined, tag?: string): string {
+  const n = personName(p);
+  if (!n) return '';
+  return [...n][0].toLocaleUpperCase(tag);
+}

package/src/lib/pluginApplies.ts

@@ -0,0 +1,123 @@
+/**
+ * pluginApplies — does an action's `applies` rule accept this selection?
+ *
+ * The client-side mirror of `wasmplugin.Matches` (backend/internal/wasmplugin/
+ * manifest.go). The server re-checks on every run; this copy only decides
+ * which rows the menu shows, so the two must agree or a row appears that the
+ * server then refuses with 422. Keep the rules in the same order as the Go:
+ *
+ *   1. an empty selection never matches;
+ *   2. more than one item needs `multi`;
+ *   3. `min` / `max` bound the count when > 0;
+ *   4. every item's kind must equal the rule's (`any` accepts both; an absent
+ *      kind means `file`);
+ *   5. `state` / `no_state` (v2): every item must carry at least one of the
+ *      rule's `state` keys and none of its `no_state` keys;
+ *   6. when the rule names extensions or mime types, every item must match
+ *      at least one of EITHER list — an ext hit is enough, a mime hit is
+ *      enough; with both lists empty anything of the right kind passes.
+ *
+ * ⚠⚠ The state keys a ROW carries are namespaced (`app_state: ["sign:pending"]`)
+ * while the keys a RULE names are bare (`state: ["pending"]`) — an action can
+ * only ever ask about its OWN plugin's keys. So the mirror needs to be told
+ * which plugin is asking (`appliesToNodes(rule, nodes, plugin)`), strips
+ * `"<plugin>:"` off the row's keys and compares what is left. Compare the two
+ * without stripping and every state rule silently never matches: the menu row
+ * simply is not there, which reads as "the app is broken", not as a bug here.
+ */
+import type { PluginApplies } from '../types/Plugins';
+
+/** What the rule sees of a selected row. */
+export interface AppliesItem {
+  kind: 'file' | 'dir' | string;
+  /** Lower-case, no dot. */
+  ext?: string | null;
+  mime?: string | null;
+  /** BARE state keys the asking plugin keeps on this item (prefix stripped). */
+  state?: string[];
+}
+
+/** A listing row, as the explorer holds it — only the three fields matter. */
+export interface AppliesNodeLike {
+  type?: string;
+  extension?: string | null;
+  mime_type?: string | null;
+  basename?: string;
+  /** `<plugin>:<key>` as the listing carries it. */
+  app_state?: string[];
+}
+
+/** The rule's own keys out of a row's namespaced ones. `''` asks about nobody. */
+export function stateKeysOf(node: AppliesNodeLike, plugin: string | undefined): string[] {
+  if (!plugin || !Array.isArray(node.app_state)) return [];
+  const prefix = `${plugin}:`;
+  return node.app_state
+    .filter((k): k is string => typeof k === 'string' && k.startsWith(prefix))
+    .map((k) => k.slice(prefix.length));
+}
+
+/** Reduce a listing row to what the rule reads. */
+export function appliesItemOf(node: AppliesNodeLike, plugin?: string): AppliesItem {
+  let ext = String(node.extension ?? '').toLowerCase();
+  if (!ext && node.basename) {
+    const dot = node.basename.lastIndexOf('.');
+    if (dot > 0) ext = node.basename.slice(dot + 1).toLowerCase();
+  }
+  return {
+    kind: node.type === 'dir' ? 'dir' : 'file',
+    ext,
+    mime: node.mime_type ?? '',
+    state: stateKeysOf(node, plugin),
+  };
+}
+
+function mimeMatches(pattern: string, mime: string): boolean {
+  if (pattern === mime) return true;
+  if (pattern.endsWith('/*')) return mime.startsWith(pattern.slice(0, -1));
+  return false;
+}
+
+/** The rule against a selection already reduced to items. */
+export function appliesMatches(rule: PluginApplies | null | undefined, items: AppliesItem[]): boolean {
+  const a = rule ?? {};
+  const n = items.length;
+  if (n === 0) return false;
+  if (n > 1 && !a.multi) return false;
+  const min = a.min ?? 0;
+  const max = a.max ?? 0;
+  if (min > 0 && n < min) return false;
+  if (max > 0 && n > max) return false;
+  const kind = a.kind || 'file';
+  const exts = (a.ext ?? []).map((e) => e.toLowerCase());
+  const mimes = (a.mime ?? []).map((m) => m.toLowerCase());
+  const wantState = a.state ?? [];
+  const banState = a.no_state ?? [];
+  for (const it of items) {
+    if (kind !== 'any' && kind !== it.kind) return false;
+    const has = it.state ?? [];
+    if (wantState.length > 0 && !wantState.some((k) => has.includes(k))) return false;
+    if (banState.some((k) => has.includes(k))) return false;
+    if (exts.length === 0 && mimes.length === 0) continue;
+    const ext = String(it.ext ?? '').toLowerCase();
+    let ok = exts.includes(ext);
+    if (!ok) {
+      const mime = String(it.mime ?? '').toLowerCase();
+      ok = mimes.some((m) => mimeMatches(m, mime));
+    }
+    if (!ok) return false;
+  }
+  return true;
+}
+
+/**
+ * The rule against listing rows. `plugin` is the ASKING action's plugin —
+ * without it a `state` / `no_state` rule can never be satisfied, so pass it
+ * wherever the action is known.
+ */
+export function appliesToNodes(
+  rule: PluginApplies | null | undefined,
+  nodes: AppliesNodeLike[],
+  plugin?: string,
+): boolean {
+  return appliesMatches(rule, nodes.map((n) => appliesItemOf(n, plugin)));
+}

package/src/lib/pluginLabel.ts

@@ -0,0 +1,72 @@
+/**
+ * pluginLabel — a plugin's multilingual text, read in the viewer's language.
+ *
+ * Mirrors `wire.Text.Get` in backend/pkg/pluginkit/wire/wire.go: the
+ * requested language, then English, then whatever is there. One place, so an
+ * action row, a surface title and a footer button cannot fall back
+ * differently.
+ */
+import type { PluginText } from '../types/Plugins';
+
+/** The text for `locale`, falling back to `en`, then to any non-empty value. */
+export function labelOf(text: PluginText | string | null | undefined, locale: string): string {
+  if (!text) return '';
+  if (typeof text === 'string') return text;
+  const lang = String(locale || 'en').toLowerCase().split('-')[0];
+  const direct = text[lang];
+  if (typeof direct === 'string' && direct !== '') return direct;
+  const en = text.en;
+  if (typeof en === 'string' && en !== '') return en;
+  for (const v of Object.values(text)) {
+    if (typeof v === 'string' && v !== '') return v;
+  }
+  return '';
+}
+
+/**
+ * The app's own words for THIS reader and nobody else: the requested
+ * language, or its base language (`pt` answers `pt-br`), and otherwise ''.
+ *
+ * Unlike `labelOf` it does NOT fall back to English — which is the whole
+ * point of `appTextOr` below.
+ */
+export function labelIn(text: PluginText | string | null | undefined, locale: string): string {
+  if (!text) return '';
+  if (typeof text === 'string') return text;
+  const lang = String(locale || 'en').toLowerCase().split('-')[0];
+  const direct = text[lang];
+  return typeof direct === 'string' && direct !== '' ? direct : '';
+}
+
+/**
+ * An app's text where FILEX HAS WORDS OF ITS OWN for the same thing — a
+ * caption an app may override, an empty state, a progress line.
+ *
+ * ⚠⚠ THE ORDER IS THE WHOLE POINT. The obvious spelling,
+ * `labelOf(appText, locale) || t(key)`, reads as "the app first, filex if the
+ * app said nothing" — but `labelOf` falls back to ENGLISH, and English is
+ * truthy, so the host string is unreachable for every reader whose language
+ * the app does not speak. Measured in v0.43.0 on the signing app's date box:
+ * an app shipping en/tr/es/de/fr, a reader in Arabic, a language pack holding
+ * filex's own Arabic for those very captions — and three English words in the
+ * middle of an Arabic screen, because the app's English won.
+ *
+ * So: the app's words for this reader, then FILEX's words, and only then
+ * whatever other language the app has — the last resort, and labelled as one.
+ *
+ * ⚠ This is for a host string that TRANSLATES THE SAME THING. Where the host
+ * string is a generic stand-in for something the app NAMES (an action's
+ * label falling back to "Confirm"), the app's own name in another language
+ * says more than filex's placeholder, and `labelOf(…) || t(…)` is right.
+ */
+export function appTextOr(
+  text: PluginText | string | null | undefined,
+  locale: string,
+  host: () => string,
+): string {
+  const mine = labelIn(text, locale);
+  if (mine) return mine;
+  const ours = host();
+  if (ours) return ours;
+  return labelOf(text, locale);
+}