@abinnovision/payloadcms-wayfinder 1.0.0-beta.2

package/dist/runtime/resolve-link.mjs

@@ -0,0 +1,89 @@
+import { variantsOf } from "../pattern/define-links.mjs";
+import { buildHref } from "./build-href.mjs";
+//#region src/runtime/resolve-link.ts
+/** Types the package resolves without a declaration. */ const BUILTIN_VARIANTS = /* @__PURE__ */ new Set([
+	"none",
+	"reference",
+	"custom",
+	"same-page"
+]);
+const newTabProps = (newTab) => newTab ? {
+	target: "_blank",
+	rel: "noopener noreferrer"
+} : {};
+/**
+* Turns a link field's value into an href.
+*
+* Internal references route through the collection mapping rather than any
+* hardcoded prefix, so changing a collection's URL pattern in the CMS updates
+* every link to it.
+*
+* Returns null rather than degrading to the site root. A link that silently
+* points somewhere plausible is harder to find than one that renders nothing.
+*
+* @param args The link value, mappings, locale and any app-declared variants.
+*/ const resolveLink = (args) => {
+	const link = args.link;
+	if (!link?.type || link.type === "none") return null;
+	const variant = variantsOf(args).find((it) => it.value === link.type);
+	if (variant?.resolve) return variant.resolve({
+		link,
+		context: args.context
+	});
+	if (link.type === "custom" && link.url) return {
+		href: link.url,
+		...newTabProps(link.newTab)
+	};
+	if (link.type === "same-page" && link.samePageIdentifier) return { href: `#${link.samePageIdentifier}` };
+	if (link.type === "reference" && link.reference) {
+		const { relationTo, value } = link.reference;
+		if (args.resolveReference) {
+			const href = args.resolveReference({
+				relationTo,
+				value,
+				locale: args.locale
+			});
+			return href ? {
+				href,
+				...newTabProps(link.newTab)
+			} : null;
+		}
+		if (typeof value === "string") {
+			args.onDiagnostic?.({
+				reason: "unpopulated-reference",
+				collection: relationTo
+			});
+			return null;
+		}
+		const href = buildHref({
+			mappings: args.mappings,
+			collection: relationTo,
+			document: value,
+			locale: args.locale,
+			...args.formatHref ? { formatHref: args.formatHref } : {},
+			...args.identifierField ? { identifierField: args.identifierField } : {},
+			...args.onDiagnostic ? { onDiagnostic: args.onDiagnostic } : {}
+		});
+		return href ? {
+			href,
+			...newTabProps(link.newTab)
+		} : null;
+	}
+	if (!BUILTIN_VARIANTS.has(link.type) && !variant) args.onDiagnostic?.({
+		reason: "unknown-variant",
+		variant: link.type
+	});
+	return null;
+};
+/**
+* Whether a link would resolve to something navigable. Use it to decide
+* whether to render a link at all, rather than emitting a dead anchor.
+*
+* @param args The same arguments as {@link resolveLink}, plus whether a label
+*   is required for the link to be worth rendering.
+*/ const isAvailableLink = (args) => {
+	if (args.withLabel && !args.link?.label) return false;
+	return resolveLink(args) !== null;
+};
+//#endregion
+export { isAvailableLink, resolveLink };

package/dist/runtime/resolve-path.d.mts

@@ -0,0 +1,54 @@
+import { PayloadCollectionMappingResolved } from "../pattern/types.mjs";
+import { PayloadCollectionMatch } from "../pattern/matcher.mjs";
+import { OnDiagnostic, ResolvePathDiagnosticReason } from "./diagnostics.mjs";
+import { Payload, Where } from "payload";
+//#region src/runtime/resolve-path.d.ts
+/**
+ * A fetched document. The concrete shape varies per collection and callers
+ * read it structurally, so it is an open record rather than the union of every
+ * generated collection type.
+ */
+type PayloadDocument = {
+  id: string | number;
+} & Record<string, unknown>;
+interface ResolvedPath {
+  match: PayloadCollectionMatch;
+  collection: string;
+  document: PayloadDocument;
+}
+/** Extra conditions to AND into the lookup. */
+type ResolvePathWhere = Where | ((args: {
+  collection: string;
+  match: PayloadCollectionMatch;
+  draft: boolean;
+}) => Where | undefined);
+interface ResolvePathToDocumentArgs {
+  payload: Payload;
+  mappings: PayloadCollectionMappingResolved[];
+  path: string;
+  locale: string;
+  /** Read drafts rather than only published documents. */
+  draft?: boolean;
+  depth?: number;
+  identifierField?: string;
+  /**
+   * Access rules, tenancy and language visibility all narrow which document
+   * a path may resolve to, and none of them belong to the package. Without
+   * this seam a project has to query twice or fork the function.
+   */
+  where?: ResolvePathWhere;
+  onDiagnostic?: OnDiagnostic<ResolvePathDiagnosticReason>;
+}
+/**
+ * Finds the document a path resolves to, or null.
+ *
+ * Candidates are tried in specificity order and the first one that actually
+ * has a document wins. Without the fallback a nested page path would be
+ * claimed by a more specific pattern and 404 even though the page exists —
+ * `/legal/imprint` also fits `/:section/:slug`.
+ *
+ * @param args The Payload instance, mappings, path and locale.
+ */
+declare const resolvePathToDocument: (args: ResolvePathToDocumentArgs) => Promise<ResolvedPath | null>;
+//#endregion
+export { PayloadDocument, ResolvePathToDocumentArgs, ResolvePathWhere, ResolvedPath, resolvePathToDocument };

package/dist/runtime/resolve-path.mjs

@@ -0,0 +1,108 @@
+import { matchCollectionMappings } from "../pattern/matcher.mjs";
+import { resolveParamQueryPath } from "../pattern/param-query-path.mjs";
+//#region src/runtime/resolve-path.ts
+/**
+* Blocks nest arbitrarily deep and read their relationships directly, so the
+* default is generous. Lower it when a project knows its own shape.
+*/ const DEFAULT_DOCUMENT_DEPTH = 10;
+/**
+* Turns the matched scope parameters into query conditions.
+*
+* Reuses the same parameter resolution the mapping validator applies at save
+* time, so a pattern that validated will query the field it promised.
+*/ const buildScopeConditions = (args) => {
+	const config = args.payload.collections[args.collection]?.config;
+	if (!config) return [];
+	return Object.entries(args.scope).flatMap(([param, value]) => {
+		const resolved = resolveParamQueryPath({
+			config,
+			param,
+			collections: args.payload.collections,
+			mappings: args.mappings,
+			locale: args.locale,
+			...args.identifierField ? { identifierField: args.identifierField } : {}
+		});
+		return "error" in resolved ? [] : [{ [resolved.queryPath]: { equals: value } }];
+	});
+};
+/**
+* Whether a collection keeps drafts.
+*
+* Payload only adds `_status` to a collection that does, so both asking for a
+* draft read and filtering on published status have to be conditional: on a
+* collection without versions the column does not exist and the query fails
+* outright rather than coming back empty.
+*/ const supportsDrafts = (payload, collection) => Boolean(payload.collections[collection]?.config.versions?.drafts);
+/**
+* Restricts a public read to published documents.
+*
+* `payload.find` with `draft: false` still returns the newest version of a
+* document, which for a drafts-enabled collection includes one that has never
+* been published. Without this a URL becomes routable the moment someone saves
+* a draft at it, which is the opposite of what turning drafts on is for.
+*/ const publishedOnly = (payload, collection, draft) => !draft && supportsDrafts(payload, collection) ? [{ _status: { equals: "published" } }] : [];
+/**
+* Finds the document a path resolves to, or null.
+*
+* Candidates are tried in specificity order and the first one that actually
+* has a document wins. Without the fallback a nested page path would be
+* claimed by a more specific pattern and 404 even though the page exists —
+* `/legal/imprint` also fits `/:section/:slug`.
+*
+* @param args The Payload instance, mappings, path and locale.
+*/ const resolvePathToDocument = async (args) => {
+	const draft = args.draft ?? false;
+	const matches = matchCollectionMappings({
+		path: args.path,
+		locale: args.locale,
+		mappings: args.mappings
+	});
+	if (matches.length === 0) {
+		args.onDiagnostic?.({
+			reason: "no-mapping",
+			path: args.path
+		});
+		return null;
+	}
+	for (const match of matches) {
+		const collection = match.mapping.collection;
+		const extra = typeof args.where === "function" ? args.where({
+			collection,
+			match,
+			draft
+		}) : args.where;
+		const document = (await args.payload.find({
+			collection,
+			locale: args.locale,
+			draft: draft && supportsDrafts(args.payload, collection),
+			overrideAccess: true,
+			limit: 1,
+			depth: args.depth ?? DEFAULT_DOCUMENT_DEPTH,
+			where: { and: [
+				{ [match.identifier.field]: { equals: match.identifier.value } },
+				...buildScopeConditions({
+					payload: args.payload,
+					collection,
+					scope: match.scope,
+					mappings: args.mappings,
+					locale: args.locale,
+					...args.identifierField ? { identifierField: args.identifierField } : {}
+				}),
+				...publishedOnly(args.payload, collection, draft),
+				...extra ? [extra] : []
+			] }
+		})).docs[0];
+		if (document) return {
+			match,
+			collection,
+			document
+		};
+	}
+	args.onDiagnostic?.({
+		reason: "no-document",
+		path: args.path
+	});
+	return null;
+};
+//#endregion
+export { resolvePathToDocument };

package/dist/runtime/resolve-relationship-slug.d.mts

@@ -0,0 +1,33 @@
+import { PayloadCollectionMappingResolved } from "../pattern/types.mjs";
+import { Payload, SanitizedCollectionConfig } from "payload";
+//#region src/runtime/resolve-relationship-slug.d.ts
+interface ResolveRelationshipSlugArgs {
+  payload: Payload;
+  /** The collection the pattern parameter belongs to. */
+  config: SanitizedCollectionConfig;
+  /** The pattern parameter naming the relationship. */
+  param: string;
+  /** The raw value held by the document being edited. */
+  value: unknown;
+  mappings?: PayloadCollectionMappingResolved[];
+  locale?: string;
+  identifierField?: string;
+}
+/**
+ * Reads the identifier value behind a relationship parameter.
+ *
+ * The inverse of `resolveParamQueryPath`: that turns a parameter into the
+ * field a path lookup queries, this turns the same parameter into the value
+ * that field holds. The admin panel is where the two have to meet — a preview
+ * URL is built from form state, where a relationship is still a bare id and
+ * there is no populated document to read a slug off, so a URL built without
+ * this would never match back.
+ *
+ * Returns null when the value names nothing resolvable, which callers should
+ * treat as "no preview URL" rather than guessing.
+ *
+ * @param args The Payload instance, the parameter and its raw value.
+ */
+declare const resolveRelationshipSlug: (args: ResolveRelationshipSlugArgs) => Promise<string | null>;
+//#endregion
+export { ResolveRelationshipSlugArgs, resolveRelationshipSlug };

package/dist/runtime/resolve-relationship-slug.mjs

@@ -0,0 +1,51 @@
+import { resolversFor } from "../pattern/resolver.mjs";
+//#region src/runtime/resolve-relationship-slug.ts
+const identifierFor = (target, args) => {
+	const fallback = args.identifierField ?? "slug";
+	if (!args.mappings || args.locale === void 0) return fallback;
+	const mapping = args.mappings.find((it) => it.collection === target);
+	const resolvers = mapping ? resolversFor(mapping, args.locale) : void 0;
+	if (!resolvers || resolvers.specificity.hasWildcard) return fallback;
+	return resolvers.paramNames.at(-1) ?? fallback;
+};
+/**
+* Reads the identifier value behind a relationship parameter.
+*
+* The inverse of `resolveParamQueryPath`: that turns a parameter into the
+* field a path lookup queries, this turns the same parameter into the value
+* that field holds. The admin panel is where the two have to meet — a preview
+* URL is built from form state, where a relationship is still a bare id and
+* there is no populated document to read a slug off, so a URL built without
+* this would never match back.
+*
+* Returns null when the value names nothing resolvable, which callers should
+* treat as "no preview URL" rather than guessing.
+*
+* @param args The Payload instance, the parameter and its raw value.
+*/ const resolveRelationshipSlug = async (args) => {
+	const field = args.config.flattenedFields.find((it) => it.name === args.param);
+	if (field?.type !== "relationship") return typeof args.value === "string" ? args.value : null;
+	const targets = Array.isArray(field.relationTo) ? field.relationTo : [field.relationTo];
+	if (args.value && typeof args.value === "object") {
+		const identifier = identifierFor(targets[0], args);
+		const held = args.value[identifier];
+		return typeof held === "string" ? held : null;
+	}
+	if (typeof args.value !== "string") return null;
+	for (const target of targets) {
+		const identifier = identifierFor(target, args);
+		try {
+			const held = (await args.payload.findByID({
+				collection: target,
+				id: args.value,
+				depth: 0,
+				select: { [identifier]: true },
+				overrideAccess: true
+			}))[identifier];
+			if (typeof held === "string") return held;
+		} catch {}
+	}
+	return null;
+};
+//#endregion
+export { resolveRelationshipSlug };

package/package.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@abinnovision/payloadcms-wayfinder",
+  "version": "1.0.0-beta.2",
+  "description": "Editor-authored URL routing for Payload: collection-to-path patterns, document-to-href building, path-to-document resolution and a routing-aware link field.",
+  "keywords": [
+    "payload",
+    "payloadcms",
+    "routing",
+    "permalinks",
+    "urls",
+    "link-field"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abinnovision/payloadcms-commons.git",
+    "directory": "packages/wayfinder"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "abi group GmbH",
+    "email": "info@abigroup.io",
+    "url": "https://abigroup.io"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.mts",
+      "default": "./dist/config/index.mjs"
+    },
+    "./lexical": {
+      "types": "./dist/lexical/index.d.mts",
+      "default": "./dist/lexical/index.mjs"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.mts",
+      "default": "./dist/admin/index.mjs"
+    },
+    "./montage": {
+      "types": "./dist/montage/index.d.mts",
+      "default": "./dist/montage/index.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "format:check": "prettier --check 'src/**/*.{ts,tsx}' 'test/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
+    "format:fix": "prettier --write 'src/**/*.{ts,tsx}' 'test/**/*.ts' '*.{json{,5},md,y{,a}ml}'",
+    "lint:check": "eslint 'src/**/*.{ts,tsx}' 'test/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.{ts,tsx}' 'test/**/*.ts' --fix",
+    "test-integration": "vitest --run --config test/integration/vitest.config.mts",
+    "test-unit": "vitest --run --coverage --config vitest.config.mts",
+    "test-unit:watch": "vitest --config vitest.config.mts",
+    "typecheck": "tsc --noEmit"
+  },
+  "lint-staged": {
+    "src/**/*.{ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json{,5},md,y{,a}ml}": "prettier --write"
+  },
+  "prettier": "@abinnovision/prettier-config",
+  "dependencies": {
+    "path-to-regexp": "^8.4.2"
+  },
+  "devDependencies": {
+    "@abinnovision/eslint-config-base": "^3.4.2",
+    "@abinnovision/payloadcms-montage": "0.0.0",
+    "@abinnovision/prettier-config": "^2.2.0",
+    "@arethetypeswrong/core": "^0.18.5",
+    "@lexical/react": "0.41.0",
+    "@payloadcms/db-sqlite": "3.88.0",
+    "@payloadcms/richtext-lexical": "3.88.0",
+    "@payloadcms/ui": "3.88.0",
+    "@swc/core": "^1.16.1",
+    "@types/node": "^26.3.0",
+    "@types/react": "^19.2.18",
+    "@vitest/coverage-v8": "^4.1.10",
+    "eslint": "^10.9.1",
+    "lexical": "0.41.0",
+    "payload": "3.88.0",
+    "prettier": "^3.9.5",
+    "publint": "^0.3.24",
+    "react": "^19.2.8",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3",
+    "unplugin-swc": "^1.5.11",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "@abinnovision/payloadcms-montage": ">=1.0.0-beta.1",
+    "@lexical/react": ">=0.35 <1",
+    "@payloadcms/richtext-lexical": ">=3.88.0 <4",
+    "@payloadcms/ui": ">=3.88.0 <4",
+    "lexical": ">=0.35 <1",
+    "payload": ">=3.88.0 <4",
+    "react": "^19"
+  },
+  "peerDependenciesMeta": {
+    "@abinnovision/payloadcms-montage": {
+      "optional": true
+    },
+    "@lexical/react": {
+      "optional": true
+    },
+    "@payloadcms/richtext-lexical": {
+      "optional": true
+    },
+    "@payloadcms/ui": {
+      "optional": true
+    },
+    "lexical": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "ghpr": true,
+    "npm": true,
+    "npmAccess": "public"
+  }
+}