@escalated-dev/escalated 0.11.1 → 0.11.3

package/package.json

@@ -1,85 +1,89 @@
 {
-  "name": "@escalated-dev/escalated",
-  "version": "0.11.1",
-  "description": "Vue 3 + Inertia.js UI components for Escalated — the embeddable support ticket system",
-  "author": "Escalated Dev <hello@escalated.dev>",
-  "license": "MIT",
-  "homepage": "https://github.com/escalated-dev/escalated",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/escalated-dev/escalated.git"
-  },
-  "keywords": [
-    "vue",
-    "inertia",
-    "support",
-    "tickets",
-    "helpdesk",
-    "escalated"
-  ],
-  "type": "module",
-  "exports": {
-    "./components/*": "./src/components/*",
-    "./pages/*": "./src/pages/*",
-    "./locales": "./src/locales/index.js",
-    "./locales/*": "./src/locales/*",
-    ".": "./src/index.js"
-  },
-  "files": [
-    "src"
-  ],
-  "peerDependencies": {
-    "@inertiajs/vue3": "^1.0.0 || ^2.0.0 || ^3.0.0",
-    "vue": "^3.3.0"
-  },
-  "dependencies": {
-    "@escalated-dev/locale": "^0.1.8"
-  },
-  "scripts": {
-    "test": "vitest run",
-    "lint": "eslint src/ --max-warnings 0",
-    "lint:fix": "eslint src/ --fix",
-    "format": "prettier --write src/",
-    "format:check": "prettier --check src/",
-    "prepare": "husky",
-    "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build",
-    "screenshot": "npx playwright test --config=playwright-screenshots.config.js",
-    "demo:serve": "node scripts/demo-server.js",
-    "demo:record": "node scripts/generate-demo.js",
-    "demo": "concurrently -k -s second \"npm run demo:serve\" \"wait-on http://localhost:3000 && npm run demo:record\""
-  },
-  "lint-staged": {
-    "*.{js,vue}": [
-      "eslint --fix",
-      "prettier --write"
-    ]
-  },
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@inertiajs/vue3": "^3.7.0",
-    "@playwright/test": "^1.62.1",
-    "@storybook/addon-a11y": "^10.6.0",
-    "@storybook/addon-docs": "^10.6.0",
-    "@storybook/vue3-vite": "^10.6.0",
-    "@tailwindcss/postcss": "^4.3.3",
-    "@vitejs/plugin-vue": "^6.0.8",
-    "@vue/test-utils": "^2.5.0",
-    "autoprefixer": "^10.5.4",
-    "concurrently": "^10.0.5",
-    "eslint": "^10.9.1",
-    "eslint-plugin-storybook": "^10.5.10",
-    "eslint-plugin-vue": "^10.10.0",
-    "happy-dom": "^20.14.0",
-    "husky": "^9.1.7",
-    "lint-staged": "^17.4.1",
-    "playwright": "^1.62.1",
-    "postcss": "^8.5.26",
-    "prettier": "^3.9.6",
-    "storybook": "^10.5.10",
-    "tailwindcss": "^4.3.3",
-    "vitest": "^5.0.0",
-    "vue": "^3.5.42",
-    "wait-on": "^9.1.0"
-  }
+    "name": "@escalated-dev/escalated",
+    "version": "0.11.3",
+    "description": "Vue 3 + Inertia.js UI components for Escalated — the embeddable support ticket system",
+    "author": "Escalated Dev <hello@escalated.dev>",
+    "license": "MIT",
+    "homepage": "https://github.com/escalated-dev/escalated",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/escalated-dev/escalated.git"
+    },
+    "keywords": [
+        "vue",
+        "inertia",
+        "support",
+        "tickets",
+        "helpdesk",
+        "escalated"
+    ],
+    "type": "module",
+    "exports": {
+        "./components/*": "./src/components/*",
+        "./pages/*": "./src/pages/*",
+        "./locales": "./src/locales/index.js",
+        "./locales/*": "./src/locales/*",
+        ".": "./src/index.js",
+        "./pages.json": "./pages.json"
+    },
+    "files": [
+        "src",
+        "pages.json"
+    ],
+    "peerDependencies": {
+        "@inertiajs/vue3": "^1.0.0 || ^2.0.0 || ^3.0.0",
+        "vue": "^3.3.0"
+    },
+    "dependencies": {
+        "@escalated-dev/locale": "^0.1.8"
+    },
+    "scripts": {
+        "test": "vitest run",
+        "lint": "eslint src/ --max-warnings 0",
+        "lint:fix": "eslint src/ --fix",
+        "format": "prettier --write src/",
+        "format:check": "prettier --check src/",
+        "prepare": "husky",
+        "storybook": "storybook dev -p 6006",
+        "build-storybook": "storybook build",
+        "screenshot": "npx playwright test --config=playwright-screenshots.config.js",
+        "demo:serve": "node scripts/demo-server.js",
+        "demo:record": "node scripts/generate-demo.js",
+        "demo": "concurrently -k -s second \"npm run demo:serve\" \"wait-on http://localhost:3000 && npm run demo:record\"",
+        "pages:manifest": "node scripts/generate-page-manifest.js",
+        "pages:check": "node scripts/generate-page-manifest.js --check"
+    },
+    "lint-staged": {
+        "*.{js,vue}": [
+            "eslint --fix",
+            "prettier --write"
+        ]
+    },
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@inertiajs/vue3": "^3.7.0",
+        "@playwright/test": "^1.62.1",
+        "@storybook/addon-a11y": "^10.6.0",
+        "@storybook/addon-docs": "^10.6.0",
+        "@storybook/vue3-vite": "^10.6.0",
+        "@tailwindcss/postcss": "^4.3.3",
+        "@vitejs/plugin-vue": "^6.0.8",
+        "@vue/test-utils": "^2.5.0",
+        "autoprefixer": "^10.5.4",
+        "concurrently": "^10.0.5",
+        "eslint": "^10.9.1",
+        "eslint-plugin-storybook": "^10.5.10",
+        "eslint-plugin-vue": "^10.10.0",
+        "happy-dom": "^20.14.0",
+        "husky": "^9.1.7",
+        "lint-staged": "^17.4.1",
+        "playwright": "^1.62.1",
+        "postcss": "^8.5.26",
+        "prettier": "^3.9.6",
+        "storybook": "^10.5.10",
+        "tailwindcss": "^4.3.3",
+        "vitest": "^5.0.0",
+        "vue": "^3.5.42",
+        "wait-on": "^9.1.0"
+    }
 }

package/pages.json

@@ -0,0 +1,95 @@
+{
+    "$comment": "Generated by scripts/generate-page-manifest.js from src/pages. Every name here resolves to a component; a name a backend renders that is not here is a blank screen.",
+    "version": "0.11.3",
+    "pages": [
+        "Escalated/Admin/ApiTokens/Index",
+        "Escalated/Admin/AuditLog/Index",
+        "Escalated/Admin/Automations/Form",
+        "Escalated/Admin/Automations/Index",
+        "Escalated/Admin/BusinessHours/Form",
+        "Escalated/Admin/BusinessHours/Index",
+        "Escalated/Admin/CannedResponses/Index",
+        "Escalated/Admin/Capacity/Index",
+        "Escalated/Admin/CustomFields/Form",
+        "Escalated/Admin/CustomFields/Index",
+        "Escalated/Admin/CustomObjects/Form",
+        "Escalated/Admin/CustomObjects/Index",
+        "Escalated/Admin/CustomObjects/Records",
+        "Escalated/Admin/Departments/Form",
+        "Escalated/Admin/Departments/Index",
+        "Escalated/Admin/EscalationRules/Form",
+        "Escalated/Admin/EscalationRules/Index",
+        "Escalated/Admin/Import/Connect",
+        "Escalated/Admin/Import/Index",
+        "Escalated/Admin/Import/Mapping",
+        "Escalated/Admin/Import/Progress",
+        "Escalated/Admin/Import/Review",
+        "Escalated/Admin/KnowledgeBase/Articles/Form",
+        "Escalated/Admin/KnowledgeBase/Articles/Index",
+        "Escalated/Admin/KnowledgeBase/Categories/Index",
+        "Escalated/Admin/Macros/Index",
+        "Escalated/Admin/Newsletters/Compose",
+        "Escalated/Admin/Newsletters/Edit",
+        "Escalated/Admin/Newsletters/Index",
+        "Escalated/Admin/Newsletters/Lists/Create",
+        "Escalated/Admin/Newsletters/Lists/Index",
+        "Escalated/Admin/Newsletters/Lists/Show",
+        "Escalated/Admin/Newsletters/Settings",
+        "Escalated/Admin/Newsletters/Show",
+        "Escalated/Admin/Newsletters/Templates/Create",
+        "Escalated/Admin/Newsletters/Templates/Index",
+        "Escalated/Admin/Newsletters/Templates/Show",
+        "Escalated/Admin/Plugins/Index",
+        "Escalated/Admin/Reports",
+        "Escalated/Admin/Reports/AgentDetail",
+        "Escalated/Admin/Reports/AgentMetrics",
+        "Escalated/Admin/Reports/AgentRanking",
+        "Escalated/Admin/Reports/Cohorts",
+        "Escalated/Admin/Reports/Comparison",
+        "Escalated/Admin/Reports/CsatReport",
+        "Escalated/Admin/Reports/Dashboard",
+        "Escalated/Admin/Reports/ResolutionTimes",
+        "Escalated/Admin/Reports/ResponseTimes",
+        "Escalated/Admin/Reports/SlaReport",
+        "Escalated/Admin/Reports/SlaTrends",
+        "Escalated/Admin/Roles/Form",
+        "Escalated/Admin/Roles/Index",
+        "Escalated/Admin/Settings",
+        "Escalated/Admin/Settings/CsatSettings",
+        "Escalated/Admin/Settings/DataRetention",
+        "Escalated/Admin/Settings/DatabaseConnection",
+        "Escalated/Admin/Settings/EmailSettings",
+        "Escalated/Admin/Settings/PublicTickets",
+        "Escalated/Admin/Settings/Sandbox",
+        "Escalated/Admin/Settings/SsoSettings",
+        "Escalated/Admin/Settings/TwoFactor",
+        "Escalated/Admin/Skills/Form",
+        "Escalated/Admin/Skills/Index",
+        "Escalated/Admin/SlaPolicies/Form",
+        "Escalated/Admin/SlaPolicies/Index",
+        "Escalated/Admin/Statuses/Form",
+        "Escalated/Admin/Statuses/Index",
+        "Escalated/Admin/Tags/Index",
+        "Escalated/Admin/Tickets/Index",
+        "Escalated/Admin/Tickets/Show",
+        "Escalated/Admin/Users/Index",
+        "Escalated/Admin/Webhooks/DeliveryLog",
+        "Escalated/Admin/Webhooks/Form",
+        "Escalated/Admin/Webhooks/Index",
+        "Escalated/Admin/Workflows/Builder",
+        "Escalated/Admin/Workflows/Form",
+        "Escalated/Admin/Workflows/Index",
+        "Escalated/Admin/Workflows/Logs",
+        "Escalated/Agent/Dashboard",
+        "Escalated/Agent/TicketIndex",
+        "Escalated/Agent/TicketShow",
+        "Escalated/Customer/Create",
+        "Escalated/Customer/Index",
+        "Escalated/Customer/KnowledgeBase/Article",
+        "Escalated/Customer/KnowledgeBase/Index",
+        "Escalated/Customer/Show",
+        "Escalated/Guest/Create",
+        "Escalated/Guest/Show",
+        "Escalated/Plugin/Page"
+    ]
+}

package/src/index.js

@@ -1,6 +1,10 @@
 // Plugin
 export { EscalatedPlugin } from './plugin';
 
+// Page resolution. A page name with no component behind it resolves to nothing
+// in Inertia -- a 200 and a blank panel -- so this says so instead.
+export { resolveEscalatedPage, isEscalatedPage, escalatedPages, suggestPages } from './resolvePage';
+
 // Components
 export { default as ActiveChatsPanel } from './components/ActiveChatsPanel.vue';
 export { default as ActivityTimeline } from './components/ActivityTimeline.vue';

package/src/resolvePage.js

@@ -0,0 +1,160 @@
+import manifest from '../pages.json';
+
+/**
+ * Resolve an Escalated page name to its component, loudly.
+ *
+ * Inertia resolves a page name to a component, and a name with nothing behind
+ * it is not an error: `resolve()` returns undefined, Vue renders nothing, and
+ * the panel comes up blank. It looks like a permissions problem or an empty
+ * dataset, and the request was a 200 the whole time — which is how four screens
+ * shipped blank across this package and its backends without anyone noticing.
+ *
+ * This wraps the lookup so an unresolvable name says so. In development it
+ * throws, naming what was asked for and the nearest thing that exists; in
+ * production it logs and hands back a component that renders the same message,
+ * because a panel that explains itself beats a panel that is empty.
+ *
+ * Wire it into the host's Inertia setup:
+ *
+ *     import { resolveEscalatedPage } from '@escalated-dev/escalated';
+ *
+ *     createInertiaApp({
+ *         resolve: (name) =>
+ *             resolveEscalatedPage(name, () =>
+ *                 resolvePageComponent(`./Pages/${name}.vue`, import.meta.glob('./Pages/**')),
+ *             ),
+ *     });
+ *
+ * @param {string} name             The page name the backend rendered.
+ * @param {Function} [fallback]     Resolver for names this package does not own.
+ * @param {Object} [options]
+ * @param {boolean} [options.throwOnMissing]  Defaults to true outside production.
+ * @returns {Promise<Object>|Object}
+ */
+export function resolveEscalatedPage(name, fallback, options = {}) {
+    const pages = import.meta.glob('./pages/**/*.vue');
+    const path = `./pages/${String(name ?? '').replace(/^Escalated\//, '')}.vue`;
+
+    if (pages[path]) {
+        return pages[path]();
+    }
+
+    // Not ours: a host page, or a plugin's. Only names this package claims are
+    // its responsibility to complain about.
+    if (!isEscalatedPage(name)) {
+        if (fallback) {
+            return fallback(name);
+        }
+
+        return missing(name, options);
+    }
+
+    return missing(name, options);
+}
+
+/** Whether a name is one this package is supposed to own. */
+export function isEscalatedPage(name) {
+    return String(name ?? '').startsWith('Escalated/');
+}
+
+/** Every page name this package can resolve. */
+export function escalatedPages() {
+    return [...manifest.pages];
+}
+
+/**
+ * Names close enough to be the one that was meant.
+ *
+ * Nearly every real instance of this has been a naming difference rather than
+ * an absent screen — `CohortAnalysis` for `Cohorts`, `New` for `Form` — so the
+ * message is far more useful when it can point at the likely intent.
+ */
+export function suggestPages(name, limit = 3) {
+    const wanted = segments(name);
+
+    if (!wanted.length) {
+        return [];
+    }
+
+    return manifest.pages
+        .map((page) => ({ page, score: similarity(wanted, segments(page)) }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.page.localeCompare(b.page))
+        .slice(0, limit)
+        .map((entry) => entry.page);
+}
+
+function segments(name) {
+    return String(name ?? '')
+        .toLowerCase()
+        .split('/')
+        .filter(Boolean);
+}
+
+/**
+ * How much two page paths have in common.
+ *
+ * Segment overlap rather than leaf equality: nearly every page ends in `Index`
+ * or `Form`, so matching on the last segment alone ranks half the package
+ * equally. What actually distinguishes the intended page is the path around it
+ * -- `Admin/KB/Articles/Index` and `Admin/KnowledgeBase/Articles/Index` share
+ * three segments and differ in one.
+ */
+function similarity(wanted, candidate) {
+    const shared = wanted.filter((part) => candidate.includes(part)).length;
+
+    if (!shared) {
+        return 0;
+    }
+
+    // The folder counts for more than the leaf, so a differently named screen
+    // in the right place outranks the same leaf somewhere unrelated.
+    const sameFolder = wanted.slice(0, -1).join('/') === candidate.slice(0, -1).join('/') ? 2 : 0;
+    const lengthPenalty = Math.abs(wanted.length - candidate.length) * 0.5;
+
+    // Every page in a folder shares its whole path, so the folder alone ranks
+    // them all equally -- `CohortAnalysis` would tie with `AgentMetrics` and
+    // lose on alphabet. How much of the name itself matches is what separates
+    // the one that was meant.
+    const leaf = commonPrefix(wanted[wanted.length - 1], candidate[candidate.length - 1]);
+
+    return shared + sameFolder + leaf - lengthPenalty;
+}
+
+/** How many leading characters two names share, as a fraction of the shorter. */
+function commonPrefix(a = '', b = '') {
+    let i = 0;
+
+    while (i < a.length && i < b.length && a[i] === b[i]) {
+        i += 1;
+    }
+
+    return i / Math.max(1, Math.min(a.length, b.length));
+}
+
+function missing(name, options) {
+    const suggestions = suggestPages(name);
+    const message =
+        `Escalated: no page component for "${name}". ` +
+        (suggestions.length
+            ? `Did you mean ${suggestions.map((s) => `"${s}"`).join(', ')}?`
+            : 'It is not in this package; a host or plugin page needs its own resolver.');
+
+    const shouldThrow = options.throwOnMissing ?? !isProduction();
+
+    if (shouldThrow) {
+        throw new Error(message);
+    }
+
+    console.error(message);
+
+    return { render: () => null, name: 'EscalatedMissingPage', __escalatedMissing: message };
+}
+
+function isProduction() {
+    try {
+        return import.meta.env?.PROD === true;
+    } catch {
+        return false;
+    }
+}