@rebasepro/app 0.13.0 → 0.13.1-canary.g3660bd5

package/dist/collections/entity-display-cache.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The store behind a computed display value.
+ *
+ * A record's title is asked for far more often than it changes, and by many
+ * components at once: a list of fifty rows, each row's relation chips, the
+ * breadcrumb above them. Resolving per component is what makes an async display
+ * value a bad idea — fifty rows becomes fifty reads, then fifty more on the next
+ * render.
+ *
+ * So resolution is keyed by record *and* role, in-flight calls are shared, and
+ * results are kept until something says otherwise. Deliberately not a React
+ * thing: the same store answers an imperative caller (an export, a breadcrumb
+ * built outside the tree), and it is testable without a renderer.
+ */
+import type { EntityDisplayRole } from "@rebasepro/admin-types";
+export type EntityDisplayKey = string;
+/** The identity of one role of one record, as a cache key. */
+export declare function entityDisplayKey(path: string, entityId: string | number | undefined, role: EntityDisplayRole): EntityDisplayKey;
+export declare class EntityDisplayCache {
+    private readonly entries;
+    private readonly listeners;
+    /**
+     * The resolved value, or `undefined` when this pair has not been resolved
+     * yet. `null` is a resolved absence, and the two must stay distinct: a
+     * caller that reads "not yet" as "nothing" flickers its fallback in on every
+     * mount.
+     */
+    peek(key: EntityDisplayKey): unknown | undefined;
+    /** True while a resolution for this pair is in flight. */
+    isLoading(key: EntityDisplayKey): boolean;
+    /**
+     * Resolve once per record and role. Concurrent callers share the first
+     * call's promise; later callers get the cached value with no promise at all.
+     *
+     * A resolver that throws is recorded as "nothing" rather than retried: the
+     * alternative is every render re-running a call that just failed. And it is
+     * reported here, which is a correction.
+     *
+     * It used to say "the caller that saw the rejection is the one that logs
+     * it", and `useEntityDisplay` duly attached a `.catch()` that warned. But
+     * both failure paths below swallow and return a *resolved* promise, so that
+     * catch could never run — the two halves each did the reasonable thing and
+     * between them the log was unreachable. A resolver that blew up produced a
+     * blank chip and total silence, which is the failure mode
+     * `EntityDisplayResolver`'s own contract ("treated as `undefined` and logged
+     * once") exists to rule out.
+     *
+     * Reporting belongs here for the reason the caller could not do it: this is
+     * the one place that runs exactly once per key, so "once" is a property of
+     * the code rather than a hope about how many components mount.
+     */
+    resolve(key: EntityDisplayKey, resolver: () => unknown): Promise<unknown>;
+    /**
+     * Drop what is known about a record, so the next ask resolves again. Called
+     * after a write: the row that just saved may be called something else now.
+     */
+    invalidate(path: string, entityId?: string | number): void;
+    /** Drop everything. The user signed out, or the app swapped datasource. */
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+    private set;
+    /**
+     * Record a failed resolution as "nothing", and say so once.
+     *
+     * The key is the message: it is `<role> <path> <id>`, which is exactly what a
+     * reader needs to find the resolver that blew up. A warning with no key would
+     * tell them a display resolver failed somewhere in a list of fifty rows.
+     *
+     * `console.warn` rather than a thrown error, because this runs while a row is
+     * rendering: the contract is that a title which cannot be fetched must not
+     * take down the row that shows it.
+     */
+    private fail;
+    private emit;
+}

package/dist/collections/entity-display.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Reading a collection's `display` block.
+ *
+ * Two questions, kept apart because they are answered at different times: which
+ * *property* fills a role (readable from values already in hand) and which
+ * *resolver* fills it (may have to go to the network). A caller that cannot
+ * await — a sort comparator, an export column, a server render — uses the key
+ * and is documented to ignore resolvers.
+ */
+import type { AdminCollection, EntityDisplayResolver, EntityDisplayRole } from "@rebasepro/admin-types";
+/**
+ * The property path a role is declared to read, when it is declared as a path.
+ *
+ * Returns `undefined` for a role filled by a resolver — a resolver has no key —
+ * and for a role the collection says nothing about, which is then derived.
+ *
+ * @group Collections
+ */
+export declare function getDisplayPropertyKey<M extends Record<string, unknown>>(collection: AdminCollection<M>, role: EntityDisplayRole): string | undefined;
+/**
+ * The resolver a role is declared to use, when it is declared as one.
+ *
+ * @group Collections
+ */
+export declare function getDisplayResolver<M extends Record<string, unknown>>(collection: AdminCollection<M>, role: EntityDisplayRole): EntityDisplayResolver<M, unknown> | undefined;
+/**
+ * True when the collection states this role at all, in either form.
+ *
+ * The derivation is a guess about what a collection probably means; a statement
+ * outranks it, and the heuristics that look for "the first enum" or "the leading
+ * relation" have to stand down when one exists.
+ *
+ * @group Collections
+ */
+export declare function hasDeclaredDisplay<M extends Record<string, unknown>>(collection: AdminCollection<M>, role: EntityDisplayRole): boolean;

package/dist/collections/entity_image_preview.d.ts

@@ -1,2 +1,10 @@
 import { CollectionConfig } from "@rebasepro/types";
+/**
+ * The property that fills a record's image slot.
+ *
+ * `admin.display.image` first, then six fallbacks in descending confidence —
+ * the first image-typed storage property, an array of them, a URL rendered as an
+ * image, and so on. The ladder stays for collections that say nothing; a
+ * collection that names its picture is not guessed at.
+ */
 export declare function getEntityImagePreviewPropertyKey<M extends Record<string, unknown>>(collection: CollectionConfig<M>): string | undefined;

package/dist/collections/form-layout.d.ts

@@ -34,6 +34,12 @@ export interface ResolvedFormSection {
     /** Initial state only; the form owns it after first interaction. */
     collapsed: boolean;
     fields: ResolvedFormField[];
+    /**
+     * Declared arrangement for the read-only view. Carried through untouched —
+     * the resolver decides *which* fields a section holds, not how the surface
+     * that renders it stacks them, and only the read view honours this.
+     */
+    readVariant?: "grid" | "summary";
 }
 export interface ResolvedFormLayout {
     sections: ResolvedFormSection[];

package/dist/collections/index.d.ts

@@ -1,9 +1,13 @@
 export * from "./collection_view_config";
 export * from "./entity_image_preview";
+export * from "./entity-display";
+export * from "./entity-display-cache";
 export * from "./filter-operator-resolution";
 export * from "./form-layout";
 export * from "./navigation_from_path";
 export * from "./navigation_utils";
 export * from "./parent_references_from_path";
+export * from "./property-path";
 export * from "./property_presentation";
+export * from "./summary-property";
 export * from "./title-property";

package/dist/collections/property-path.d.ts

@@ -0,0 +1,16 @@
+import type { Properties, Property } from "@rebasepro/types";
+/**
+ * The property at a dotted path, walking `map` children — `address.street`.
+ *
+ * The value counterpart is `getValueInPath` in `@rebasepro/utils`; this is the
+ * schema half, and the two have to be used together. Reading a dotted path off
+ * an entity while looking its property up with a flat `properties[path]` gives
+ * the value and `undefined` for how to render it, which is how a declared title
+ * on a nested field silently fell back to a derived one.
+ *
+ * There were three copies of this: one private to `useColumnsIds`, one exported
+ * from the admin layer, and the flat lookup in the title resolver that was not
+ * this function at all. This is the one, in the lowest layer that needs it —
+ * admin re-exports it under the name it already published.
+ */
+export declare function getPropertyInPath(properties: Properties, path: string): Property | undefined;

package/dist/collections/summary-property.d.ts

@@ -0,0 +1,65 @@
+import type { Property } from "@rebasepro/types";
+/**
+ * Whether a property can stand in for a record in *one line*.
+ *
+ * Preview surfaces — the reference card, a list row, a board card — have a
+ * single line per property and no way to grow. That is a constraint on the
+ * *value*, not on the property's importance: a Markdown biography is the most
+ * interesting column on an author, and it is still the wrong thing to paste
+ * into a 44px card. Ranking it here means the picker can skip it without
+ * anyone having to configure their way out of a broken card.
+ *
+ * Kept beside {@link getTitlePropertyCandidates} because the two answer
+ * neighbouring questions — "what is this record called" and "what else can be
+ * said about it in a line" — from the same property schema.
+ *
+ * @group Collections
+ */
+export declare const SUMMARY_RANK: {
+    /**
+     * No single-line form exists. A map renders as a key/value table and an
+     * array of maps as a stack of them; there is no first line to take.
+     */
+    readonly UNUSABLE: 0;
+    /**
+     * Readable in one line, but only as an excerpt — the property holds a
+     * document, and the line is its opening. Worth showing when nothing better
+     * is available, never in preference to a value that fits whole.
+     */
+    readonly EXCERPT: 1;
+    /** Short and self-contained: the line *is* the value. */
+    readonly DIRECT: 2;
+};
+/** One of the three summary ranks. */
+export type SummaryRank = typeof SUMMARY_RANK[keyof typeof SUMMARY_RANK];
+/**
+ * File-storage backed content (single image, array of images, generic upload…).
+ * Preview surfaces give these their own image slot, so they are never also a
+ * text line.
+ *
+ * @group Collections
+ */
+export declare function isStorageProperty(property: Property | undefined): boolean;
+/**
+ * True when the property holds free text long enough to be a document rather
+ * than a value — Markdown, or an explicitly multi-line string.
+ *
+ * @group Collections
+ */
+export declare function isLongTextProperty(property: Property | undefined): boolean;
+/**
+ * How well a property reads as one line of a preview. See {@link SUMMARY_RANK}.
+ *
+ * Decided from the property *schema* only: no values are consulted, so the
+ * answer is stable for a collection and can be memoised per collection rather
+ * than per row.
+ *
+ * @group Collections
+ */
+export declare function rankSummaryProperty(property: Property | undefined): SummaryRank;
+/**
+ * True when the property has any single-line form at all.
+ *
+ * @group Collections
+ */
+export declare function canSummariseProperty(property: Property | undefined): boolean;