@brftech/filex-core 0.42.1 → 0.43.0

package/src/styles/sign-fonts.css

@@ -0,0 +1,118 @@
+/**
+ * sign-fonts.css — the five faces a signature may be written in.
+ *
+ * Three handwriting (Caveat, Dancing Script, Homemade Apple) and two formal
+ * (the interface face, Source Serif 4): the closed set `pdf-fields` and
+ * `signature-pad` offer, mirrored by `lib/signFonts.ts` (which is what the
+ * components and the wire value read — keep the two in step).
+ *
+ * ⚠⚠ Self-hosted on purpose. A CDN `@font-face` on a signing screen tells a
+ * third party that somebody, at this address, is signing a document right
+ * now — and on an air-gapped install it silently draws the signature in the
+ * wrong face. The `.woff2` files live in `../assets/fonts/`; the bundler
+ * emits them beside `style.css`, so every host of the package gets them
+ * without wiring anything. See that folder's README for licences.
+ *
+ * ⚠ These rules cost nothing until they are used: a browser fetches a
+ * `@font-face` file only when text is actually laid out in that family, and
+ * `unicode-range` narrows it further to the subset the text needs.
+ *
+ * ⚠ `unicode-range` is copied from the upstream stylesheet. Without it the
+ * browser would download the latin-ext file for a plain ASCII name, and —
+ * worse — would NOT fall back to the interface face for a glyph the subset
+ * does not carry (Homemade Apple has no latin-ext at all: `ş ğ İ` come from
+ * the fallback, which is exactly the intended behaviour).
+ */
+
+/* ── Caveat (OFL 1.1) ─────────────────────────────────────────────────── */
+@font-face {
+  font-family: 'Caveat';
+  font-style: normal;
+  font-weight: 400 700;
+  font-display: swap;
+  src: url('../assets/fonts/caveat-latin-ext.woff2') format('woff2');
+  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308,
+    U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113,
+    U+2C60-2C7F, U+A720-A7FF;
+}
+@font-face {
+  font-family: 'Caveat';
+  font-style: normal;
+  font-weight: 400 700;
+  font-display: swap;
+  src: url('../assets/fonts/caveat-latin.woff2') format('woff2');
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304,
+    U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+/* ── Dancing Script (OFL 1.1) ─────────────────────────────────────────── */
+@font-face {
+  font-family: 'Dancing Script';
+  font-style: normal;
+  font-weight: 400 700;
+  font-display: swap;
+  src: url('../assets/fonts/dancing-script-latin-ext.woff2') format('woff2');
+  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308,
+    U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113,
+    U+2C60-2C7F, U+A720-A7FF;
+}
+@font-face {
+  font-family: 'Dancing Script';
+  font-style: normal;
+  font-weight: 400 700;
+  font-display: swap;
+  src: url('../assets/fonts/dancing-script-latin.woff2') format('woff2');
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304,
+    U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+/* ── Homemade Apple (Apache 2.0) — latin only, see the folder README ──── */
+@font-face {
+  font-family: 'Homemade Apple';
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url('../assets/fonts/homemade-apple-latin.woff2') format('woff2');
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304,
+    U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+/* ── Source Serif 4 (OFL 1.1) ─────────────────────────────────────────── */
+@font-face {
+  font-family: 'Source Serif 4';
+  font-style: normal;
+  font-weight: 200 900;
+  font-display: swap;
+  src: url('../assets/fonts/source-serif-4-latin-ext.woff2') format('woff2');
+  unicode-range: U+0100-02BA, U+02BD-02C5, U+02C7-02CC, U+02CE-02D7, U+02DD-02FF, U+0304, U+0308,
+    U+0329, U+1D00-1DBF, U+1E00-1E9F, U+1EF2-1EFF, U+2020, U+20A0-20AB, U+20AD-20C0, U+2113,
+    U+2C60-2C7F, U+A720-A7FF;
+}
+@font-face {
+  font-family: 'Source Serif 4';
+  font-style: normal;
+  font-weight: 200 900;
+  font-display: swap;
+  src: url('../assets/fonts/source-serif-4-latin.woff2') format('woff2');
+  unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+0304,
+    U+0308, U+0329, U+2000-206F, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
+}
+
+/* The CSS stack each key resolves to. One definition, read by the pad, by
+   the pdf-fields overlay and by anything that later renders a stored value:
+   a second copy is how a signature drawn in Caveat comes back in Inter. */
+.fe-signfont--caveat {
+  font-family: 'Caveat', cursive;
+}
+.fe-signfont--dancing-script {
+  font-family: 'Dancing Script', cursive;
+}
+.fe-signfont--homemade-apple {
+  font-family: 'Homemade Apple', cursive;
+}
+.fe-signfont--inter {
+  font-family: var(--fe-font);
+}
+.fe-signfont--source-serif {
+  font-family: 'Source Serif 4', Georgia, 'Times New Roman', serif;
+}

package/src/styles/variables.css

@@ -64,6 +64,14 @@
    * new width in Turkish, the longer of the two catalogues — the widest row
    * label ("Paylaşılanlar") clears it, and so does the quota line. */
   --fe-sidenav-w: 192px;
+  /* The list view's FROZEN LEAD — how far from the pane's left edge the Name
+   * column's sticky offset sits, i.e. the width of the tick's track plus the
+   * gap after it. Declared here because it is a real default and because a
+   * `--fe-*` nobody declares is a name nobody can find (web/tests/api/
+   * themeTokens.test.ts), even though ListView writes the exact number inline:
+   * only the component knows the tick's track, and it recomputes it whenever
+   * the metrics change. */
+  --fe-list-lead: calc(var(--fe-h-sm) + var(--fe-gap) + var(--fe-gap-sm));
   /* Type scale. Small and tight on purpose: the shell packs a filename, a
    * size, a date and a menu into one row, and 14px with normal leading pushes
    * that to two lines at any realistic column width. */
@@ -246,3 +254,55 @@
      it changes nothing visually, it only makes the token real. */
   --fe-ok: #16a34a;
 }
+
+/* === The outward-facing page's own ground and card =====================
+ * The public shell (`/s/`, `/d/`, an app's public page) does NOT paint with
+ * `--fe-bg` / `--fe-bg-elev`: in the app those two mean "surface" and
+ * "sunken strip", and a card on a page has to sit ABOVE its ground, not
+ * below it. Drawing the card in `--fe-bg-elev` on `--fe-bg` is exactly what
+ * made the v0.43.0 public page look like no page at all.
+ *
+ * The values are the Go-rendered page's own, up to v0.42.2 (`--px-bg1`,
+ * `--px-bg2`, `--px-card`, `--px-shadow`).
+ *
+ * ⚠ Declared HERE, in both variants, and not beside the rules that use them:
+ * web/tests/api/themeTokens.test.ts reads this file alone, and a `--fe-*`
+ * declared anywhere else is a phantom token to every other reader. */
+.fe.fe-ppage {
+  --fe-ppage-ground-1: #f5f7fb;
+  --fe-ppage-ground-2: #e9edf4;
+  --fe-ppage-card: #ffffff;
+  --fe-ppage-shadow: 0 12px 40px rgba(15, 23, 42, 0.1);
+  --fe-ppage-ok: var(--fe-ok);
+  /* The card's width, set by the shell's `layout` (lib/publicLayout):
+     the gate's 400px here, 520 and 880 below. */
+  --fe-ppage-max: 400px;
+}
+.fe.fe-ppage.fe--theme-dark,
+:root[data-theme='dark'] .fe.fe-ppage,
+:root.dark .fe.fe-ppage,
+.dark .fe.fe-ppage {
+  --fe-ppage-ground-1: #12151a;
+  --fe-ppage-ground-2: #191e25;
+  --fe-ppage-card: #1f242c;
+  --fe-ppage-shadow: 0 12px 40px rgba(0, 0, 0, 0.45);
+  --fe-ppage-ok: #22c55e;
+}
+@media (prefers-color-scheme: dark) {
+  .fe.fe-ppage:not(.fe--theme-light) {
+    --fe-ppage-ground-1: #12151a;
+    --fe-ppage-ground-2: #191e25;
+    --fe-ppage-card: #1f242c;
+    --fe-ppage-shadow: 0 12px 40px rgba(0, 0, 0, 0.45);
+    --fe-ppage-ok: #22c55e;
+  }
+}
+/* ⚠ `.fe.` on purpose: `.fe.fe-ppage` above is (0,2,0), so a single-class
+   modifier LOSES to it and every card came out at the gate's 400px —
+   measured on the folder and the signing page at 1440. */
+.fe.fe-ppage--form {
+  --fe-ppage-max: 520px;
+}
+.fe.fe-ppage--wide {
+  --fe-ppage-max: 880px;
+}

package/src/types/Connections.ts

@@ -46,6 +46,23 @@ export interface StorageField {
   monospace?: boolean;
   multiline?: boolean;
   advanced?: boolean;
+  /**
+   * Draw the choice as BUTTONS rather than a dropdown — every option on the
+   * screen, readable without clicking (`components/ChoiceButtons`).
+   *
+   * ⚠ Set by the DECLARATION, not by the surface drawing it. An app
+   * plugin's fields always carry it (v3 §2: "no dropdowns anywhere in a
+   * surface", applied by `lib/surfaceValues.storageFieldOf`), and a storage
+   * driver may ask for it on a short choice. Branching on "am I in a
+   * surface?" inside the renderer would be the same control behaving two
+   * ways on two screens, which is the thing this package keeps un-writing.
+   *
+   * On a `bool` it means the two-button Yes/No decision; a bool without it
+   * stays the on/off checkbox a driver setting wants.
+   */
+  choice?: boolean;
+  /** A `select` that takes several of its options; the value is then a list. */
+  multi?: boolean;
   /** THE field that scopes the storage inside the backend (s3 prefix,
    *  local path, sftp/ftp/webdav root). The backend rejects an empty or
    *  "/" value with ROOT_PATH_FORBIDDEN. */

package/src/types/ExplorerConfig.ts

@@ -43,7 +43,14 @@ export type AuthConfig =
   | { type: 'csrf'; csrf: string };
 
 export type ThemeMode = 'light' | 'dark' | 'auto';
-export type LocaleCode = 'tr' | 'en';
+/**
+ * A language code. `tr` and `en` are the two this package ships a catalogue
+ * for; ANY other tag may arrive too — a language pack (an app whose manifest
+ * carries `ui_locales`) adds languages at run time, see `lib/uiLocales`.
+ * `(string & {})` keeps the two named ones in autocompletion without
+ * pretending they are the only ones.
+ */
+export type LocaleCode = 'tr' | 'en' | (string & {});
 
 /**
  * Resolved endpoint map. `useFileApi` derives this once on construction
@@ -84,6 +91,16 @@ export interface EndpointMap {
   /* wiring:e2 */
   e2eEscrowChallenge: string | null;
   e2eEscrowUsed: string | null;
+  /* App plugins (docs/APP-PLUGINS-API.md). Templates carry `{plugin}`,
+   * `{action}`, `{view}` and `{id}` placeholders, filled at call time. */
+  pluginActions: string | null;
+  pluginActionRun: string | null;
+  pluginView: string | null;
+  pluginViewEvent: string | null;
+  /** `?plugin=<name>&q=` — the people-picker's user lookup (M2). */
+  pluginUsers: string | null;
+  /** `POST` cancel of a queued/running ops row — `{id}` placeholder. */
+  opsCancel: string | null;
 }
 
 export interface ExplorerConfig {
@@ -132,6 +149,59 @@ export interface ExplorerConfig {
   /** Single op show endpoint — `{id}` placeholder. */
   opsShow?: string;
 
+  /** Cancel a queued/running op — `{id}` placeholder (plugin jobs). */
+  opsCancel?: string;
+
+  /** App plugins: the actions list, the run template (`{plugin}`/`{action}`),
+   *  the view template (`{plugin}`/`{view}`) and its `/event` sibling. */
+  pluginActions?: string;
+  pluginActionRun?: string;
+  pluginView?: string;
+  pluginViewEvent?: string;
+  pluginUsers?: string;
+
+  /**
+   * App plugins (file-menu rows drawn from WebAssembly plugins).
+   *
+   * Absent: follow the server — `capabilities.app_plugins.enabled`. `false`
+   * switches the feature off for this instance whatever the server says, and
+   * the explorer then makes no plugin request at all. `true` asks even when
+   * the capabilities answer is missing (a host that knows its backend).
+   */
+  plugins?: boolean;
+
+  /**
+   * Where this host serves the SPA, for an app plugin's `page` view
+   * (`${pluginPageBase}apps/{plugin}/{view}?path=…`, lib/pluginPage).
+   *
+   * ⚠ A mount BASE, not the site root: the same bundle is served from
+   * `/admin/` and `/drive/`, and only those prefixes fall back to index.html
+   * for an `apps/…` address, so a bare `/apps/…` is a 404 on the server. The
+   * host passes the prefix it was itself served from.
+   *
+   * Absent: a `page` action falls back to the modal — the same conversation
+   * in a dialog. A degraded frame, never a missing feature.
+   */
+  pluginPageBase?: string;
+
+  /**
+   * How this host opens a plugin page. Return `true` when the host handled
+   * it; anything else lets the explorer open a browser tab itself.
+   *
+   * ⚠ The hook exists for shells that have no tabs to open: the desktop app
+   * wants its own window (and a `window.open` there lands in the system
+   * browser with no session), an embed inside another product may want a
+   * panel. The RULE — which actions open a page, and what the address is —
+   * stays in the package for all of them (lib/pluginPage).
+   */
+  openPluginPage?: (target: {
+    plugin: string;
+    view: string;
+    path?: string;
+    /** The address the explorer would open, already built from `pluginPageBase`. */
+    url: string;
+  }) => boolean | void;
+
   /**
    * OnlyOffice config endpoint. Backend POST returns
    * `{ config, documentServerUrl }` where `config` is a JWT-signed
@@ -186,6 +256,52 @@ export interface ExplorerConfig {
   /** Show the virtual `.trash/` entry in the root listing. */
   trashVisible?: boolean;
 
+  /**
+   * paylas:m1 — show the navigation panel's **My shares** row: the public
+   * links THIS person handed out, directly under its mirror "Shared with me".
+   *
+   * Default: OFF, and it is the only row in that group whose default is off
+   * for a reason that has nothing to do with taste. Every other entry either
+   * opens a listing this component owns (Home, Recent, Starred, Trash, a tag,
+   * a storage) or a panel it draws itself ("How to connect", "API keys") —
+   * this one opens a page of the HOST. The explorer can announce the intent
+   * (`open-my-shares`) and nothing more; a host that does not listen is left
+   * with a row that draws, takes a click and does nothing at all. Off by
+   * default is therefore the honest default: `<filex-explorer>` on
+   * work.example.com, in the fishapp and on fm.example.com has no such page, and a dead
+   * row is worse than a missing one.
+   *
+   * ⚠ Opting in is a promise, not a preference: set it to `true` only if you
+   * handle `@open-my-shares`. The SPA does (`web/src/views/Explore.vue` pushes
+   * its `my-shares` route), which is why it is the one host that asks for it.
+   * Only the Vue component emits it: `<filex-explorer>` and the React
+   * `<FileManager>` do not forward `open-my-shares`, so there it cannot be
+   * handled and the flag must stay off.
+   *
+   * ⚠ ANDed with `callerKind`, never ORed: an app token is not a person and
+   * has shared nothing, so the row goes with its mirror even for a host that
+   * asked for it. See `callerKind`.
+   */
+  mySharesVisible?: boolean;
+
+  /**
+   * The host draws an app plugin's `home` view as a page of ITS OWN, in the
+   * same tab (the SPA's `app-home` route), and handles `@open-app-home`.
+   *
+   * ⚠⚠ The owner, 2026-09-21: the Signatures screen opened as a dialog over
+   * the file list, and it should be "its own page" — the way My shares is,
+   * with its sections in a menu, the Back button working, and a
+   * notification landing on the right section. The explorer cannot give a
+   * host a page; it can only say which one was asked for, so the navigation
+   * panel's "Apps" row emits `open-app-home` when this is on.
+   *
+   * Default: OFF, for the reason `mySharesVisible` is off — only the Vue
+   * component emits the event, and a host that does not listen would be
+   * left with a row that does nothing. Off, an "Apps" row keeps opening the
+   * view in a dialog, which is a smaller frame but a working one.
+   */
+  appHomePage?: boolean;
+
   /** UI dil kodu */
   locale?: LocaleCode;
 

package/src/types/FileNode.ts

@@ -4,6 +4,8 @@
  * Backend `?q=index` (or `GET /api/files/manager?action=index`) returns:
  *   { adapter, storages, dirname, files: FileNode[] }
  */
+import type { AppLock } from './Plugins';
+
 export interface FileNode {
   /** DB node ID — needed by the per-user meta routes (starred, tags,
    *  recently-opened). Backend's projectFileNodes() emits it for every
@@ -42,9 +44,49 @@ export interface FileNode {
    *  projectFileNodes emits it when a storage has RBAC on). '' / undefined =
    *  ACL not enforced. Used to gate edit/manage affordances client-side. */
   perm?: 'none' | 'viewer' | 'editor' | 'owner';
+  /** The row sits on a read-only storage. Carried by the rows that come from
+   *  OUTSIDE a folder listing — Recent, Starred, a tag view, the Home cards,
+   *  the Recently-opened tray (`handlers/meta.go`) — because there the
+   *  listing-level `read_only` has no folder to describe. A folder listing's
+   *  rows leave it unset; `dirReadOnly` answers for the whole folder. Folded
+   *  into the write gate with `perm`, so the context menu is the same in
+   *  every view. */
+  read_only?: boolean;
   /* wiring:e2 — dir rows: true when the folder is E2E-encrypted (carries a
    * `.filex-e2e.json` marker). Drives the 🔒 badge in the listings. */
   e2e?: boolean;
+  /** An app plugin holds this file read-only (docs/APP-PLUGINS-API.md →
+   *  "File locks"). `perm` already arrives capped at `viewer` for everyone,
+   *  administrators included — the flag is what the badge and the details
+   *  panel say out loud, and what turns the server's 423 into words. */
+  locked?: boolean;
+  lock?: AppLock;
+  /** The state keys apps keep on this file, `<plugin>:<key>`. Read by the
+   *  menu's state-aware rows (`applies.state` / `no_state`). */
+  app_state?: string[];
+  /** Issue #34 — this row is a symlink the SERVER WILL NOT FOLLOW. A link
+   *  whose target is inside the storage root IS followed and arrives as that
+   *  target (a linked directory is a `dir` and opens normally), so this flag
+   *  always means "cannot be opened", never merely "is a link".
+   *
+   *  ⚠ Additive, and `type` stays the closed `'file' | 'dir'` union it has
+   *  always been: widening it would be a breaking change for every embedder
+   *  of `@brftech/filex`, so the backend reports such a row as a file and
+   *  flags it here (`handlers/manager.go`). A client that does not know the
+   *  flag renders exactly the row it rendered before — which is precisely the
+   *  0-byte-file-that-will-not-open the issue was filed about, and why
+   *  `lib/symlink` exists. */
+  symlink?: boolean;
+  /** Why it will not open — `outside_root` | `broken` | `unresolved`.
+   *
+   *  ⚠⚠ Absent far more often than present: only the cold-cache driver
+   *  listing carries it. The normal DB-backed listing sends `symlink: true`
+   *  alone, because `model.Node` has no column for a fact that belongs to the
+   *  link as it is RIGHT NOW rather than as it was at scan time. Read it
+   *  through `lib/symlink.linkStateOf`, which answers `'unknown'` for that
+   *  case — and for a state a newer server invents — instead of dropping the
+   *  row back into silence. */
+  link_state?: string;
   /** Generic — any additional fields the backend wants to inline. */
   [k: string]: unknown;
 }
@@ -118,6 +160,15 @@ export interface Capabilities {
    *  ExplorerConfig.callerKind. Absent on a server older than the app/user
    *  token split, which is why every reader treats "missing" as a person. */
   caller_kind?: 'user' | 'app';
+  /** Could this caller set up a missing optional service (ONLYOFFICE,
+   *  draw.io, the converter…)? An administrator who can reach the instance
+   *  settings — not a tenant admin, not an API token. Decides between "greyed
+   *  with where to fix it" and "not offered" (lib/serviceGate). Absent on an
+   *  older server, which reads as "no". */
+  caller_admin?: boolean;
+  /** App plugins (docs/APP-PLUGINS-API.md). Absent or `enabled: false` → the
+   *  explorer makes no plugin request at all. */
+  app_plugins?: { enabled: boolean };
   /** The address this deployment is reached at — only when it is real (the
    *  operator configured it, or the request came in on a tenant's host).
    *  Read by the connection guides; see `connectionsOrigin`. */
@@ -126,7 +177,14 @@ export interface Capabilities {
     onlyoffice?: ExternalServiceStatus;
     drawio?: ExternalServiceStatus;
     mermaid?: ExternalServiceStatus;
+    /** The file converter. ⚠ `convert_url` is filled whenever the service is
+     *  ENABLED, healthy or not — the menu reads this for health. */
+    convert?: ExternalServiceStatus;
   };
+  /** Can outgoing mail be sent right now (SMTP configured AND verified)?
+   *  Absent on an older server or one with no mailer wired — read as "yes",
+   *  i.e. keep offering mail the way it always was. */
+  mail?: { ready: boolean };
   /* wiring:e2 */
   /** Whether this installation holds an escrow key for E2E-encrypted folders,
    *  and the public half the browser wraps new folders' master keys to.