@rebasepro/common 0.10.0 → 0.10.1-canary.14e53ae

package/dist/util/index.d.ts

@@ -8,6 +8,7 @@ export * from "./resolutions";
 export * from "./policy";
 export * from "./permissions";
 export * from "./references";
+export * from "./title-property";
 export * from "./navigation_from_path";
 export * from "./parent_references_from_path";
 export * from "./builders";

package/dist/util/title-property.d.ts

@@ -0,0 +1,43 @@
+import type { CollectionConfig } from "@rebasepro/types";
+/**
+ * All properties that could serve as the entity title, best first.
+ *
+ * Candidates are ranked from the property *schema* — identifiers (primary
+ * keys, foreign keys, UUID columns, user pickers), images and hidden fields are
+ * excluded structurally, so a collection whose id column is called something
+ * other than `id` is handled the same as one where it isn't.
+ *
+ * When the collection declares `propertiesOrder` the developer has already
+ * stated what comes first, so qualifying candidates keep that order; otherwise
+ * they are ranked (a name beats a description beats a relation).
+ *
+ * @group Collections
+ */
+export declare function getTitlePropertyCandidates<M extends Record<string, unknown>>(collection: CollectionConfig<M>): string[];
+/**
+ * The property that should fill the title slot for a collection, ignoring any
+ * concrete values. Prefer {@link getTitlePropertyKeyForValues} when an entity
+ * is at hand — it can skip candidates that happen to be empty or to hold an id.
+ *
+ * @group Collections
+ */
+export declare function getTitlePropertyKey<M extends Record<string, unknown>>(collection: CollectionConfig<M>): string | undefined;
+/**
+ * True when a value reads as a machine identifier (UUID, ObjectId/long hex,
+ * cuid) rather than as something worth showing to a person.
+ *
+ * @group Collections
+ */
+export declare function looksLikeIdentifierValue(value: unknown): boolean;
+/**
+ * The title property for a concrete entity: the best-ranked candidate that
+ * actually carries a readable value. Candidates that are empty, that repeat the
+ * entity id, or that hold an opaque identifier are skipped, so a free-text
+ * column that happens to store UUIDs never ends up as the title.
+ *
+ * Returns the top-ranked candidate when none of them has a usable value, so
+ * callers can still render a placeholder for that property.
+ *
+ * @group Collections
+ */
+export declare function getTitlePropertyKeyForValues<M extends Record<string, unknown>>(collection: CollectionConfig<M>, values: Record<string, unknown> | undefined, entityId?: string | number): string | undefined;

package/dist/util/title-property.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/common",
   "type": "module",
-  "version": "0.10.0",
+  "version": "0.10.1-canary.14e53ae",
   "description": "Awesome Firebase/Firestore-based headless open-source CMS",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -40,8 +40,8 @@
   "dependencies": {
     "fast-equals": "6.0.0",
     "json-logic-js": "^2.0.5",
-    "@rebasepro/types": "0.10.0",
-    "@rebasepro/utils": "0.10.0"
+    "@rebasepro/types": "0.10.1-canary.14e53ae",
+    "@rebasepro/utils": "0.10.1-canary.14e53ae"
   },
   "devDependencies": {
     "@jest/globals": "^30.4.1",

package/src/util/index.ts

@@ -8,6 +8,7 @@ export * from "./resolutions";
 export * from "./policy";
 export * from "./permissions";
 export * from "./references";
+export * from "./title-property";
 export * from "./navigation_from_path";
 export * from "./parent_references_from_path";
 export * from "./builders";

package/src/util/title-property.test.ts

@@ -0,0 +1,343 @@
+import { CollectionConfig } from "@rebasepro/types";
+import {
+    getTitlePropertyCandidates,
+    getTitlePropertyKey,
+    getTitlePropertyKeyForValues,
+    looksLikeIdentifierValue
+} from "./title-property";
+
+describe("Title property resolution", () => {
+
+    describe("identifiers never fill the title slot", () => {
+
+        it("ranks a userSelect below a real name", () => {
+            // Regression: `auth_user_id` is declared before `full_name` and is a
+            // plain string, so "first non-id string" picked the auth user UUID.
+            // A user picker resolves to a person, so it stays a candidate — but
+            // only behind every plain text field.
+            const collection: CollectionConfig = {
+                name: "Talents",
+                slug: "talents",
+                table: "talents",
+                properties: {
+                    id: { name: "ID",
+type: "string",
+isId: "uuid" },
+                    auth_user_id: { name: "Auth User ID",
+type: "string",
+userSelect: true },
+                    full_name: { name: "Full Name",
+type: "string" },
+                    email: { name: "Email",
+type: "string" }
+                }
+            };
+            expect(getTitlePropertyCandidates(collection)).toEqual(["full_name", "email", "auth_user_id"]);
+        });
+
+        it("skips the primary key even when it is not called `id`", () => {
+            const collection: CollectionConfig = {
+                name: "Devices",
+                slug: "devices",
+                table: "devices",
+                properties: {
+                    serial: { name: "Serial",
+type: "string",
+isId: "uuid" },
+                    model: { name: "Model",
+type: "string" }
+                }
+            };
+            expect(getTitlePropertyKey(collection)).toBe("model");
+        });
+
+        it("skips uuid columns and declared foreign keys", () => {
+            const collection: CollectionConfig = {
+                name: "Orders",
+                slug: "orders",
+                table: "orders",
+                properties: {
+                    id: { name: "ID",
+type: "string",
+isId: "uuid" },
+                    external_ref: { name: "External ref",
+type: "string",
+columnType: "uuid" },
+                    customer_id: { name: "Customer id",
+type: "string" },
+                    customer: {
+                        name: "Customer",
+                        type: "relation",
+                        target: "customers",
+                        cardinality: "one",
+                        localKey: "customer_id"
+                    },
+                    reference: { name: "Reference",
+type: "string" }
+                }
+            };
+            expect(getTitlePropertyKey(collection)).toBe("reference");
+        });
+
+        it("skips a foreign key whose column name was left to be inferred", () => {
+            const collection: CollectionConfig = {
+                name: "Posts",
+                slug: "posts",
+                table: "posts",
+                properties: {
+                    id: { name: "ID",
+type: "string",
+isId: "uuid" },
+                    author_id: { name: "Author id",
+type: "string" },
+                    author: {
+                        name: "Author",
+                        type: "relation",
+                        target: "users",
+                        cardinality: "one"
+                    },
+                    headline: { name: "Headline",
+type: "string" }
+                }
+            };
+            expect(getTitlePropertyKey(collection)).toBe("headline");
+        });
+    });
+
+    describe("ranking", () => {
+
+        it("prefers a name-like key over an earlier plain string", () => {
+            const collection: CollectionConfig = {
+                name: "Products",
+                slug: "products",
+                table: "products",
+                properties: {
+                    sku: { name: "SKU",
+type: "string" },
+                    title: { name: "Title",
+type: "string" }
+                }
+            };
+            expect(getTitlePropertyKey(collection)).toBe("title");
+        });
+
+        it("prefers plain text over email, enum, description and relation", () => {
+            const collection: CollectionConfig = {
+                name: "Leads",
+                slug: "leads",
+                table: "leads",
+                properties: {
+                    owner: { name: "Owner",
+type: "relation",
+target: "users",
+cardinality: "one" },
+                    bio: { name: "Bio",
+type: "string",
+ui: { multiline: true } },
+                    status: {
+                        name: "Status",
+                        type: "string",
+                        enum: { new: "New",
+won: "Won" }
+                    },
+                    email: { name: "Email",
+type: "string",
+email: true },
+                    company: { name: "Company",
+type: "string" }
+                }
+            };
+            expect(getTitlePropertyCandidates(collection))
+                .toEqual(["company", "email", "status", "bio", "owner"]);
+        });
+
+        it("falls back to a relation when the collection holds no text", () => {
+            const collection: CollectionConfig = {
+                name: "Posts tags",
+                slug: "posts_tags",
+                table: "posts_tags",
+                properties: {
+                    id: { name: "ID",
+type: "string",
+isId: "uuid" },
+                    tag: { name: "Tag",
+type: "relation",
+target: "tags",
+cardinality: "one",
+localKey: "tag_id" }
+                }
+            };
+            expect(getTitlePropertyKey(collection)).toBe("tag");
+        });
+
+        it("honours an explicit titleProperty", () => {
+            const collection: CollectionConfig = {
+                name: "Talents",
+                slug: "talents",
+                table: "talents",
+                titleProperty: "email",
+                properties: {
+                    full_name: { name: "Full Name",
+type: "string" },
+                    email: { name: "Email",
+type: "string" }
+                }
+            };
+            expect(getTitlePropertyKey(collection)).toBe("email");
+        });
+
+        it("ignores hidden and image properties", () => {
+            const collection: CollectionConfig = {
+                name: "Assets",
+                slug: "assets",
+                table: "assets",
+                properties: {
+                    internal_code: {
+                        name: "Internal code",
+                        type: "string",
+                        ui: { hideFromCollection: true }
+                    },
+                    picture: {
+                        name: "Picture",
+                        type: "string",
+                        storage: { storagePath: "assets" }
+                    },
+                    caption: { name: "Caption",
+type: "string" }
+                }
+            };
+            expect(getTitlePropertyKey(collection)).toBe("caption");
+        });
+    });
+
+    describe("explicit propertiesOrder", () => {
+
+        it("keeps the declared order instead of reranking", () => {
+            const collection: CollectionConfig = {
+                name: "Databases",
+                slug: "databases",
+                table: "databases",
+                properties: {
+                    id: { name: "ID",
+type: "string",
+isId: "uuid" },
+                    project: { name: "Project",
+type: "relation",
+target: "projects",
+cardinality: "one" },
+                    connection_string: { name: "Connection string",
+type: "string" }
+                },
+                propertiesOrder: ["id", "project", "connection_string"]
+            };
+            expect(getTitlePropertyKey(collection)).toBe("project");
+        });
+
+        it("still skips identifiers declared first", () => {
+            const collection: CollectionConfig = {
+                name: "Talents",
+                slug: "talents",
+                table: "talents",
+                properties: {
+                    id: { name: "ID",
+type: "string",
+isId: "uuid" },
+                    external_ref: { name: "External ref",
+type: "string",
+columnType: "uuid" },
+                    tenant_id: { name: "Tenant id",
+type: "string" },
+                    tenant: {
+                        name: "Tenant",
+                        type: "relation",
+                        target: "tenants",
+                        cardinality: "one",
+                        localKey: "tenant_id"
+                    },
+                    full_name: { name: "Full Name",
+type: "string" }
+                },
+                propertiesOrder: ["id", "external_ref", "tenant_id", "full_name"]
+            };
+            expect(getTitlePropertyKey(collection)).toBe("full_name");
+        });
+
+        it("lets a declared user picker win, since it renders the person", () => {
+            const collection: CollectionConfig = {
+                name: "Assignments",
+                slug: "assignments",
+                table: "assignments",
+                properties: {
+                    id: { name: "ID",
+type: "string",
+isId: "uuid" },
+                    assignee: { name: "Assignee",
+type: "string",
+userSelect: true },
+                    notes: { name: "Notes",
+type: "string" }
+                },
+                propertiesOrder: ["id", "assignee", "notes"]
+            };
+            expect(getTitlePropertyKey(collection)).toBe("assignee");
+        });
+    });
+
+    describe("value-aware resolution", () => {
+
+        const collection: CollectionConfig = {
+            name: "Talents",
+            slug: "talents",
+            table: "talents",
+            properties: {
+                id: { name: "ID",
+type: "string",
+isId: "uuid" },
+                full_name: { name: "Full Name",
+type: "string" },
+                email: { name: "Email",
+type: "string" }
+            }
+        };
+
+        it("uses the top candidate when it holds a value", () => {
+            expect(getTitlePropertyKeyForValues(collection, {
+                full_name: "Priscila Alaniz",
+                email: "palaniz@peersocial.com.mx"
+            })).toBe("full_name");
+        });
+
+        it("falls through when the top candidate is empty", () => {
+            expect(getTitlePropertyKeyForValues(collection, {
+                full_name: "",
+                email: "palaniz@peersocial.com.mx"
+            })).toBe("email");
+        });
+
+        it("falls through when the top candidate holds an id", () => {
+            expect(getTitlePropertyKeyForValues(collection, {
+                full_name: "fdda6c2a-5310-4b0c-87cc-a13eb36e5167",
+                email: "palaniz@peersocial.com.mx"
+            })).toBe("email");
+        });
+
+        it("keeps the top candidate when nothing has a usable value", () => {
+            expect(getTitlePropertyKeyForValues(collection, {})).toBe("full_name");
+        });
+    });
+
+    describe("looksLikeIdentifierValue", () => {
+        it("detects uuids, long hex and cuids", () => {
+            expect(looksLikeIdentifierValue("fdda6c2a-5310-4b0c-87cc-a13eb36e5167")).toBe(true);
+            expect(looksLikeIdentifierValue("507f1f77bcf86cd799439011")).toBe(true);
+            expect(looksLikeIdentifierValue("cjld2cjxh0000qzrmn831i7rn")).toBe(true);
+        });
+
+        it("leaves human text alone", () => {
+            expect(looksLikeIdentifierValue("Priscila Alaniz")).toBe(false);
+            expect(looksLikeIdentifierValue("Consultoría ambiental")).toBe(false);
+            expect(looksLikeIdentifierValue("")).toBe(false);
+            expect(looksLikeIdentifierValue(42)).toBe(false);
+        });
+    });
+});

package/src/util/title-property.ts

@@ -0,0 +1,264 @@
+import type { CollectionConfig, Property, Relation } from "@rebasepro/types";
+import { generateForeignKeyName } from "@rebasepro/utils";
+import { isPropertyBuilder } from "./entities";
+import { getPrimaryKeys } from "./collections";
+
+/**
+ * How good a property is as the human-readable title of an entity.
+ * Higher wins; ties are broken by declaration order.
+ * `DISQUALIFIED` means the property can never be a title.
+ */
+const SCORE = {
+    DISQUALIFIED: -1,
+    /**
+     * Points at another entity. Only readable once the target resolves, and it
+     * renders as the raw key until then — last resort, for collections (like
+     * junction tables) that hold no text of their own.
+     */
+    REFERENCE: 5,
+    RELATION: 10,
+    /** A user picker: resolves to a person's name, like a relation does */
+    USER: 10,
+    /** Long form text — readable, but a description, not a name */
+    LONG_TEXT: 20,
+    /** A closed set of values: shared by many rows, so it identifies nothing */
+    ENUM: 30,
+    /** Identifying, but PII and usually secondary to a name */
+    EMAIL: 45,
+    /** Any plain, short, free text field */
+    PLAIN_TEXT: 60,
+    /** Free text whose name says it holds the entity's label */
+    NAMED: 100
+} as const;
+
+/**
+ * Keys whose name states outright that the property is the entity label.
+ * This is a *bonus* on top of the structural rules — never a requirement, and
+ * never the mechanism that keeps identifiers out of the title slot.
+ */
+const TITLE_LIKE_KEYS = new Set([
+    "name",
+    "fullname",
+    "displayname",
+    "title",
+    "label",
+    "heading",
+    "subject",
+    "username",
+    "nickname"
+]);
+
+function normalizeKey(key: string): string {
+    return key.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function isHidden(property: Property): boolean {
+    return Boolean(property.ui?.hideFromCollection);
+}
+
+/**
+ * File-storage backed content (single image, array of images, generic upload…).
+ * Rendered by the dedicated image slot, so never a title.
+ */
+function isStorageProperty(property: Property): boolean {
+    if (property.type === "string" && (property.storage || property.ui?.url === "image")) return true;
+    if (property.type === "array" && property.of && !Array.isArray(property.of)) {
+        const inner = property.of;
+        if (inner.type === "string" && (inner.storage || inner.ui?.url === "image")) return true;
+    }
+    return false;
+}
+
+/**
+ * Every column on this collection that stores a foreign key: the `localKey` of
+ * each owning relation (declared inline on a property or in `relations[]`), the
+ * source column of a junction, and the key a many-to-many joins on.
+ *
+ * These hold another entity's id, so they must never fill the title slot even
+ * though they are declared as plain strings.
+ */
+function getForeignKeyColumns<M extends Record<string, unknown>>(collection: CollectionConfig<M>): Set<string> {
+    const keys = new Set<string>();
+
+    const addRelationKeys = (relation: Pick<Relation, "localKey" | "through" | "joinPath">) => {
+        if (relation.localKey) keys.add(relation.localKey);
+        if (relation.through?.sourceColumn) keys.add(relation.through.sourceColumn);
+        // Only the first hop of a join path starts on this collection's table.
+        const firstStep = relation.joinPath?.[0];
+        if (firstStep) {
+            const from = firstStep.on?.from;
+            for (const column of Array.isArray(from) ? from : [from]) {
+                if (column) keys.add(column);
+            }
+        }
+    };
+
+    for (const relation of collection.relations ?? []) {
+        addRelationKeys(relation);
+    }
+
+    for (const [key, propertyRaw] of Object.entries(collection.properties ?? {})) {
+        const property = propertyRaw as Property | undefined;
+        if (!property || isPropertyBuilder(property) || property.type !== "relation") continue;
+        addRelationKeys(property);
+        if (property.relation) addRelationKeys(property.relation);
+        // An owning one-to-one whose localKey was left to be inferred still
+        // consumes a column; assume the conventional `<relation>_id` name.
+        if ((property.cardinality ?? "one") === "one" && (property.direction ?? "owning") === "owning") {
+            keys.add(generateForeignKeyName(property.relationName || key));
+        }
+    }
+
+    return keys;
+}
+
+/**
+ * True when the property is declared to hold an opaque identifier rather than
+ * something a person reads: a primary key, a foreign key, a UUID column, or a
+ * picker bound to an auth user id. Decided from the property *schema*, never
+ * from the key name.
+ */
+function isIdentifierProperty(property: Property, key: string, idKeys: Set<string>, foreignKeys: Set<string>): boolean {
+    if (idKeys.has(key)) return true;
+    if (foreignKeys.has(key)) return true;
+    if ("isId" in property && property.isId) return true;
+    if (property.type === "string" && property.columnType === "uuid") return true;
+    return false;
+}
+
+function scoreTitleCandidate(property: Property, key: string, idKeys: Set<string>, foreignKeys: Set<string>): number {
+    if (isHidden(property)) return SCORE.DISQUALIFIED;
+    if (isIdentifierProperty(property, key, idKeys, foreignKeys)) return SCORE.DISQUALIFIED;
+    if (isStorageProperty(property)) return SCORE.DISQUALIFIED;
+
+    if (property.type === "relation") {
+        const isMany = property.cardinality === "many" || property.relation?.cardinality === "many";
+        return isMany ? SCORE.DISQUALIFIED : SCORE.RELATION;
+    }
+    if (property.type === "reference") {
+        return SCORE.REFERENCE;
+    }
+    if (property.type !== "string") {
+        // Numbers, dates, booleans, maps and arrays never read as a title.
+        return SCORE.DISQUALIFIED;
+    }
+
+    // A user picker stores an auth user id but renders the person behind it, so
+    // it ranks with relations: usable as a title, but only as a last resort.
+    if (property.userSelect) return SCORE.USER;
+    if (property.enum) return SCORE.ENUM;
+    if (property.ui?.multiline || property.ui?.markdown) return SCORE.LONG_TEXT;
+    if (property.email) return SCORE.EMAIL;
+    if (TITLE_LIKE_KEYS.has(normalizeKey(key))) return SCORE.NAMED;
+    return SCORE.PLAIN_TEXT;
+}
+
+/**
+ * All properties that could serve as the entity title, best first.
+ *
+ * Candidates are ranked from the property *schema* — identifiers (primary
+ * keys, foreign keys, UUID columns, user pickers), images and hidden fields are
+ * excluded structurally, so a collection whose id column is called something
+ * other than `id` is handled the same as one where it isn't.
+ *
+ * When the collection declares `propertiesOrder` the developer has already
+ * stated what comes first, so qualifying candidates keep that order; otherwise
+ * they are ranked (a name beats a description beats a relation).
+ *
+ * @group Collections
+ */
+export function getTitlePropertyCandidates<M extends Record<string, unknown>>(
+    collection: CollectionConfig<M>
+): string[] {
+    if (!collection.properties) return [];
+
+    if (collection.titleProperty && collection.properties[collection.titleProperty as string]) {
+        return [collection.titleProperty as string];
+    }
+
+    const idKeys = new Set<string>(getPrimaryKeys(collection) as string[]);
+    const foreignKeys = getForeignKeyColumns(collection);
+    const explicitOrder = collection.propertiesOrder as string[] | undefined;
+    const order = explicitOrder ?? Object.keys(collection.properties);
+
+    const scored: { key: string; score: number; index: number }[] = [];
+    order.forEach((key, index) => {
+        const property = collection.properties[key];
+        if (!property || isPropertyBuilder(property)) return;
+        const score = scoreTitleCandidate(property as Property, key, idKeys, foreignKeys);
+        if (score === SCORE.DISQUALIFIED) return;
+        scored.push({ key,
+score,
+index });
+    });
+
+    // An explicit `propertiesOrder` is a statement of what matters first, so it
+    // wins over the ranking — the ranking only decides between properties the
+    // developer never ordered.
+    if (!explicitOrder) {
+        scored.sort((a, b) => (b.score - a.score) || (a.index - b.index));
+    }
+
+    return scored.map(candidate => candidate.key);
+}
+
+/**
+ * The property that should fill the title slot for a collection, ignoring any
+ * concrete values. Prefer {@link getTitlePropertyKeyForValues} when an entity
+ * is at hand — it can skip candidates that happen to be empty or to hold an id.
+ *
+ * @group Collections
+ */
+export function getTitlePropertyKey<M extends Record<string, unknown>>(
+    collection: CollectionConfig<M>
+): string | undefined {
+    return getTitlePropertyCandidates(collection)[0];
+}
+
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const LONG_HEX_REGEX = /^[0-9a-f]{24,}$/i;
+const CUID_REGEX = /^c[a-z0-9]{20,}$/i;
+
+/**
+ * True when a value reads as a machine identifier (UUID, ObjectId/long hex,
+ * cuid) rather than as something worth showing to a person.
+ *
+ * @group Collections
+ */
+export function looksLikeIdentifierValue(value: unknown): boolean {
+    if (typeof value !== "string") return false;
+    const trimmed = value.trim();
+    return UUID_REGEX.test(trimmed) || LONG_HEX_REGEX.test(trimmed) || CUID_REGEX.test(trimmed);
+}
+
+/**
+ * The title property for a concrete entity: the best-ranked candidate that
+ * actually carries a readable value. Candidates that are empty, that repeat the
+ * entity id, or that hold an opaque identifier are skipped, so a free-text
+ * column that happens to store UUIDs never ends up as the title.
+ *
+ * Returns the top-ranked candidate when none of them has a usable value, so
+ * callers can still render a placeholder for that property.
+ *
+ * @group Collections
+ */
+export function getTitlePropertyKeyForValues<M extends Record<string, unknown>>(
+    collection: CollectionConfig<M>,
+    values: Record<string, unknown> | undefined,
+    entityId?: string | number
+): string | undefined {
+    const candidates = getTitlePropertyCandidates(collection);
+    if (!values || candidates.length === 0) return candidates[0];
+
+    for (const key of candidates) {
+        const value = values[key];
+        if (value === undefined || value === null || value === "") continue;
+        if (typeof value === "string") {
+            if (looksLikeIdentifierValue(value)) continue;
+            if (entityId !== undefined && value === String(entityId)) continue;
+        }
+        return key;
+    }
+
+    return candidates[0];
+}