@rebasepro/cms 0.17.3 → 0.18.1

package/src/hooks/useEntityDisplay.tsx

@@ -1,262 +0,0 @@
-import type { AdminCollection, EntityDisplayRole } from "@rebasepro/cms-types";
-import type { Entity, Property } from "@rebasepro/types";
-import { ENTITY_DISPLAY_ROLES } from "@rebasepro/cms-types";
-import { useEffect, useMemo, useSyncExternalStore } from "react";
-import {
-    EntityDisplayCache,
-    entityDisplayKey,
-    getDisplayPropertyKey,
-    getDisplayResolver,
-    getPropertyInPath,
-    useRebaseContext
-} from "@rebasepro/app";
-import { getValueInPath } from "@rebasepro/utils";
-
-import { getEntityTitlePropertyKeyForEntity, isUserSelectProperty, resolveTitleToString } from "../util/previews";
-import { getUserLabel, useResolvedUser } from "./useResolvedUsers";
-
-/**
- * What fills one display role for one record.
- *
- * `value` is `undefined` rather than a placeholder when nothing resolved,
- * because the substitute differs by surface and each one knows its own better
- * than this hook does: a page heading wants the singular collection name, a link
- * wants the id, a draft wants "New customer". A single baked-in fallback is
- * exactly what produced three different ones scattered across the consumers.
- */
-export interface ResolvedDisplayValue<T = unknown> {
-    /** What goes in the slot. `undefined` when the record has nothing for it. */
-    value: T | undefined;
-    /**
-     * A resolver is in flight, and `value` currently holds the derived answer or
-     * nothing. Surfaces that can show a skeleton may; none has to.
-     */
-    loading: boolean;
-    /**
-     * Set only when the value came from a property of this collection. Carries
-     * what a rich renderer needs — a status shows as its enum's coloured chip,
-     * an image as a storage thumbnail — which a bare resolved string cannot
-     * describe.
-     */
-    source?: {
-        key: string;
-        property: Property | undefined;
-        value: unknown;
-    };
-}
-
-/**
- * One shared store, so every surface agrees on a record and resolves it once.
- *
- * Module-level rather than a provider: two app instances on one page share a
- * cache keyed by collection path and record id, which *is* the same record.
- * Nothing here is user-specific — a resolver that reads per-user data must
- * invalidate on sign-out, which {@link useEntityDisplayCache} exposes.
- */
-let sharedCache: EntityDisplayCache | undefined;
-
-/**
- * The store behind {@link useEntityDisplay}, for invalidating after a write.
- *
- * Built on first use rather than at module scope. Importing a module should not
- * construct anything: it runs during SSR where there is nothing to cache, and it
- * made this module unimportable from any test that stubs `@rebasepro/app` —
- * which several do, and which is a legitimate thing for them to do.
- */
-export function useEntityDisplayCache(): EntityDisplayCache {
-    if (!sharedCache) sharedCache = new EntityDisplayCache();
-    return sharedCache;
-}
-
-export interface UseEntityDisplayParams<M extends Record<string, unknown>> {
-    /**
-     * Optional because several callers look the collection up in the registry by
-     * path and may not find it — a relation into a collection the panel does not
-     * register. A hook that could not be called until that succeeded would have
-     * to sit below an early return, which is not where hooks go.
-     */
-    collection?: AdminCollection<M>;
-    /**
-     * The record. A resolver is handed the whole entity — its id and path are
-     * how it reaches anything the record does not carry — so a computed value is
-     * only available once there is an entity to compute it from.
-     */
-    entity?: Entity<M>;
-    /**
-     * Values to read a declared path from when they are newer than the entity:
-     * the live form values while editing. Falls back to `entity.values`.
-     */
-    values?: Record<string, unknown>;
-    /** Set false to skip resolver work entirely — a draft has nothing to show. */
-    enabled?: boolean;
-}
-
-/**
- * What fills one display role of one record.
- *
- * This is the only implementation. Before it there were seven for the title
- * alone — the identity bar, the detail header, inline previews, reference cards,
- * list slots, relation chips and the headless view — each re-deriving it from
- * `collection.properties` and disagreeing about the answer.
- *
- * Resolution order, per role:
- *
- * 1. `admin.display[role]` as a **resolver** — awaited, cached per record and
- *    role, with the derived value showing meanwhile so nothing flickers empty.
- * 2. `admin.display[role]` as a **property path** (or, for the title, the
- *    deprecated `titleProperty`).
- * 3. The **derived** answer: for the title, the best-ranked property carrying a
- *    readable value; for the rest, today's per-role heuristics.
- *
- * A user-picker title resolves to the person behind the id, as it always did —
- * that path is now here rather than in two of the seven.
- */
-export function useEntityDisplay<T = unknown, M extends Record<string, unknown> = Record<string, unknown>>(
-    role: EntityDisplayRole,
-    {
-        collection,
-        entity,
-        values: valuesProp,
-        enabled = true
-    }: UseEntityDisplayParams<M>
-): ResolvedDisplayValue<T> {
-
-    const context = useRebaseContext();
-    const cache = useEntityDisplayCache();
-
-    const values = valuesProp ?? entity?.values;
-
-    /* ---- the declared or derived key ------------------------------------- */
-
-    // The title is the one role with a ranking behind it: several candidates,
-    // best first, skipping the ones that hold nothing for *this* record. The
-    // others are a single declared or derived key.
-    const declaredKey = collection ? getDisplayPropertyKey(collection, role) : undefined;
-    const propertyKey = collection && role === "title" && !declaredKey
-        ? getEntityTitlePropertyKeyForEntity(collection, values, entity?.id)
-        : declaredKey;
-
-    const rawValue = values && propertyKey ? getValueInPath(values, propertyKey) : undefined;
-
-    // A user picker stores an auth id and renders the person: resolved like a
-    // relation, and hooked unconditionally so the hook order never changes.
-    const titleUser = useResolvedUser(
-        collection && role === "title" && isUserSelectProperty(collection, propertyKey) && typeof rawValue === "string"
-            ? rawValue
-            : undefined
-    );
-
-    const derived = useMemo<T | undefined>(() => {
-        if (titleUser) return getUserLabel(titleUser) as T;
-        if (rawValue === undefined || rawValue === null) return undefined;
-        // Only text roles get flattened to a string; a date stays a date and an
-        // image stays whatever the storage property holds, so the renderer can
-        // still format them.
-        if (role === "title" || role === "subtitle" || role === "status") {
-            return (resolveTitleToString(rawValue) || undefined) as T | undefined;
-        }
-        return rawValue as T;
-    }, [titleUser, rawValue, role]);
-
-    /* ---- the computed answer --------------------------------------------- */
-
-    const resolver = collection ? getDisplayResolver(collection, role) : undefined;
-    const canResolve = Boolean(enabled && resolver && entity);
-    const key = entity ? entityDisplayKey(entity.path, entity.id, role) : undefined;
-
-    const resolved = useSyncExternalStore<unknown>(
-        // Subscribing unconditionally keeps the hook order stable. The store
-        // only notifies when an entry changes, so a collection with no resolver
-        // never re-renders from it.
-        cb => cache.subscribe(cb),
-        () => (canResolve && key ? cache.peek(key) : undefined),
-        // Server render: nothing is resolved, so every slot starts at its
-        // fallback and hydration does not disagree with the markup.
-        () => undefined
-    );
-
-    const loading = Boolean(canResolve && key && resolved === undefined);
-
-    useEffect(() => {
-        if (!canResolve || !key || !resolver || !entity) return;
-        if (cache.peek(key) !== undefined) return;
-        cache.resolve(key, () => resolver({
-            entity,
-            context
-        })).catch(() => {
-            // Unreachable, and kept only so it stays that way: `resolve` records a
-            // failure as "nothing" and returns a RESOLVED promise, which is why
-            // the warning that used to live here could never run — see the note on
-            // `EntityDisplayCache.resolve`. The cache reports the failure itself
-            // now, once per key. This exists so that if `resolve` ever starts
-            // rejecting, it surfaces as a caught no-op rather than an unhandled
-            // rejection during render.
-        });
-    }, [cache, canResolve, key, resolver, entity, context, role]);
-
-    /* ---- the answer ------------------------------------------------------ */
-
-    // A resolver that produced nothing falls back to the derived value rather
-    // than to blank: it said this record has no computed answer for the role,
-    // not that the role should be empty.
-    const computed = canResolve && resolved !== null ? resolved as T | undefined : undefined;
-    const value = computed ?? derived;
-
-    return useMemo(() => ({
-        value,
-        loading,
-        source: collection && propertyKey && value === derived && derived !== undefined
-            ? {
-                key: propertyKey,
-                property: getPropertyInPath(collection.properties, propertyKey),
-                value: rawValue
-            }
-            : undefined
-    }), [value, loading, propertyKey, derived, collection, rawValue]);
-}
-
-/**
- * Every display role of a record at once — what a list row, a card or a board
- * card needs, in one call rather than six.
- *
- * The role list is iterated from {@link ENTITY_DISPLAY_ROLES} so the hook order
- * is fixed and adding a role does not mean editing every caller.
- */
-export function useEntityDisplayValues<M extends Record<string, unknown>>(
-    params: UseEntityDisplayParams<M>
-): Record<EntityDisplayRole, ResolvedDisplayValue> & { loading: boolean } {
-
-    // Not a loop over `useEntityDisplay`: the number of hooks a component calls
-    // has to be fixed at compile time, and a role added to the array later would
-    // silently change it. Written out, it is checked by the return type.
-    const title = useEntityDisplay<string, M>("title", params);
-    const subtitle = useEntityDisplay<string, M>("subtitle", params);
-    const image = useEntityDisplay<string, M>("image", params);
-    const status = useEntityDisplay<string, M>("status", params);
-    const date = useEntityDisplay<Date | string | number, M>("date", params);
-    const tags = useEntityDisplay<string[] | string, M>("tags", params);
-
-    return useMemo(() => ({
-        title,
-        subtitle,
-        image,
-        status,
-        date,
-        tags,
-        loading: title.loading || subtitle.loading || image.loading
-            || status.loading || date.loading || tags.loading
-    }), [title, subtitle, image, status, date, tags]);
-}
-
-/**
- * What the record is called — the one role asked for often enough on its own to
- * deserve a name.
- */
-export function useEntityTitle<M extends Record<string, unknown>>(
-    params: UseEntityDisplayParams<M>
-): ResolvedDisplayValue<string> {
-    return useEntityDisplay<string, M>("title", params);
-}
-
-/** Re-exported so a caller can iterate roles without reaching into types. */
-export { ENTITY_DISPLAY_ROLES };

package/src/hooks/useEntityDisplayTitle.tsx

@@ -1,49 +0,0 @@
-import type { AdminCollection } from "@rebasepro/cms-types";
-import type { Entity, EntityStatus } from "@rebasepro/types";
-import { useEntityTitle } from "./useEntityDisplay";
-
-export interface UseEntityDisplayTitleParams<M extends Record<string, unknown>> {
-    collection: AdminCollection<M>;
-    /** The record. Needed for a computed title; see {@link useEntityTitle}. */
-    entity?: Entity<M>;
-    /** Live form values, when they are ahead of the entity. */
-    values?: Record<string, unknown>;
-    status: EntityStatus;
-}
-
-/**
- * The heading for a record: the identity bar and the breadcrumb.
- *
- * Everything about *what a record is called* lives in {@link useEntityTitle}.
- * What is left here is the heading's own two rules, which are presentation, not
- * identity:
- *
- * The guard on `status` is the first. The title resolver returns the first
- * candidate carrying a value, and on a brand new entity the only values are the
- * property defaults — so creating a blog post opened a page headed **draft**,
- * the default of its `status` enum. A record that does not exist yet has no
- * name; it has an intent.
- *
- * The fallback is the second. A page needs a heading even when the record has
- * nothing readable in it, and the honest one is what kind of thing it is.
- */
-export function useEntityDisplayTitle<M extends Record<string, unknown>>({
-    collection,
-    entity,
-    values,
-    status
-}: UseEntityDisplayTitleParams<M>): string {
-
-    const isNew = status === "new";
-    const singular = collection.singularName ?? collection.name;
-
-    const { value: title } = useEntityTitle<M>({
-        collection,
-        entity,
-        values,
-        enabled: !isNew
-    });
-
-    if (isNew) return `New ${singular.toLowerCase()}`;
-    return title ?? singular;
-}

package/src/hooks/useHistory.ts

@@ -1,178 +0,0 @@
-import { useCallback, useEffect, useRef, useState, useMemo } from "react";
-import { useApiBase, useApiConfig } from "@rebasepro/app";
-import type { EntityHistoryEntry } from "@rebasepro/types";
-
-/**
- * What the history REST endpoint returns. The fourth declaration of this shape
- * — the two drivers had one each and disagreed on `updated_at` — now an alias
- * of the one in `@rebasepro/types`.
- */
-export type HistoryEntryData = EntityHistoryEntry;
-
-export interface UseEntityHistoryResult {
-    entries: HistoryEntryData[];
-    total: number;
-    isLoading: boolean;
-    hasMore: boolean;
-    error?: Error;
-    loadMore: () => void;
-    revert: (historyId: string) => Promise<Record<string, unknown>>;
-}
-
-/**
- * Hook to fetch entity history from the backend REST API.
- * Replaces the old subcollection-based approach with a proper API call.
- */
-export function useHistory(params: {
-    slug: string;
-    entityId: string | number | undefined;
-    enabled?: boolean;
-    pageSize?: number;
-    /**
-     * Bumped by the caller when the record is saved. A save is the one event
-     * that adds a revision, and nothing else here would notice it: without
-     * this the open panel keeps showing the list it fetched when it opened,
-     * so the revision you just created never appears.
-     */
-    refreshToken?: number;
-}): UseEntityHistoryResult {
-    const { slug, entityId, enabled = true, pageSize = 10, refreshToken } = params;
-    const apiConfig = useApiConfig();
-    const apiBase = useApiBase();
-
-    const [entries, setEntries] = useState<HistoryEntryData[]>([]);
-    const [total, setTotal] = useState(0);
-    const [isLoading, setIsLoading] = useState(false);
-    const [hasMore, setHasMore] = useState(true);
-    const [error, setError] = useState<Error | undefined>();
-    const [offset, setOffset] = useState(0);
-    const [refreshTrigger, setRefreshTrigger] = useState(0);
-
-    // Track the current entity identity so we can detect stale responses.
-    // `refreshToken` is part of the identity on purpose: a save makes the list
-    // we are holding a stale page of a longer list, which is the same problem
-    // as having moved to a different record.
-    const entityKey = `${slug}/${entityId}/${refreshToken ?? 0}`;
-    const currentEntityRef = useRef<string | undefined>(undefined);
-
-    const fetchEntries = useCallback(async (
-        currentOffset: number,
-        signal?: AbortSignal
-    ) => {
-        if (!apiConfig?.apiUrl || !entityId || !enabled) return;
-
-        setIsLoading(true);
-        setError(undefined);
-
-        try {
-            const token = await apiConfig.getAuthToken?.();
-            const headers: Record<string, string> = {
-                "Content-Type": "application/json"
-            };
-            if (token) headers["Authorization"] = `Bearer ${token}`;
-
-            const url = `${apiBase}/data/${slug}/${entityId}/history?limit=${pageSize}&offset=${currentOffset}`;
-            const response = await fetch(url, { headers,
-signal });
-
-            // Check if the request was aborted or the entity changed while in-flight
-            if (signal?.aborted) return;
-            if (currentEntityRef.current !== entityKey) return;
-
-            if (!response.ok) {
-                const errorData = await response.json().catch(() => ({ error: { message: response.statusText } }));
-                throw new Error(errorData.error?.message || `Failed to fetch history (${response.status})`);
-            }
-
-            const result = await response.json();
-
-            if (currentOffset === 0) {
-                setEntries(result.data);
-            } else {
-                setEntries(prev => [...prev, ...result.data]);
-            }
-
-            setTotal(result.meta.total);
-            setHasMore(result.meta.hasMore);
-        } catch (err) {
-            // Don't set error state for intentional aborts
-            if (err instanceof DOMException && err.name === "AbortError") return;
-            setError(err instanceof Error ? err : new Error(String(err)));
-        } finally {
-            setIsLoading(false);
-        }
-    }, [apiConfig, apiBase, slug, entityId, entityKey, enabled, pageSize]);
-
-    // Single unified effect: reset state when entity changes, fetch when offset changes.
-    // Uses AbortController to cancel stale requests on entity change or unmount.
-    useEffect(() => {
-        const isNewEntity = currentEntityRef.current !== entityKey;
-
-        if (isNewEntity) {
-            // Reset state for new entity
-            currentEntityRef.current = entityKey;
-            setEntries([]);
-            setTotal(0);
-            setHasMore(true);
-            setOffset(0);
-        }
-
-        if (!enabled || !entityId) return;
-
-        const abortController = new AbortController();
-        // When entity changed, always fetch from offset 0
-        const effectiveOffset = isNewEntity ? 0 : offset;
-        fetchEntries(effectiveOffset, abortController.signal);
-
-        return () => {
-            abortController.abort();
-        };
-    }, [fetchEntries, offset, enabled, entityId, entityKey, refreshTrigger]);
-
-    const loadMore = useCallback(() => {
-        if (!isLoading && hasMore && offset + entries.length < total) {
-            setOffset(prev => prev + pageSize);
-        }
-    }, [isLoading, hasMore, pageSize, offset, entries.length, total]);
-
-    const revert = useCallback(async (historyId: string): Promise<Record<string, unknown>> => {
-        if (!apiConfig?.apiUrl || !entityId) {
-            throw new Error("Cannot revert: missing API configuration or entity ID");
-        }
-
-        const token = await apiConfig.getAuthToken?.();
-        const headers: Record<string, string> = {
-            "Content-Type": "application/json"
-        };
-        if (token) headers["Authorization"] = `Bearer ${token}`;
-
-        const url = `${apiBase}/data/${slug}/${entityId}/history/${historyId}/revert`;
-        const response = await fetch(url, { method: "POST",
-headers });
-
-        if (!response.ok) {
-            const errorData = await response.json().catch(() => ({ error: { message: response.statusText } }));
-            throw new Error(errorData.error?.message || `Failed to revert (${response.status})`);
-        }
-
-        const result = await response.json();
-
-        // Refresh the history list after revert by resetting the entity ref
-        // and triggering the effect.
-        currentEntityRef.current = undefined;
-        setRefreshTrigger(prev => prev + 1);
-
-        // Return the reverted entity data so callers can update the form
-        return result.data as Record<string, unknown>;
-    }, [apiConfig, apiBase, slug, entityId]);
-
-    return useMemo(() => ({
-        entries,
-        total,
-        isLoading,
-        hasMore,
-        error,
-        loadMore,
-        revert
-    }), [entries, total, isLoading, hasMore, error, loadMore, revert]);
-}

package/src/hooks/useRecordActions.tsx

@@ -1,69 +0,0 @@
-import type { EntityAction, AdminCollection } from "@rebasepro/cms-types";
-import type { Entity } from "@rebasepro/types";
-import { useMemo } from "react";
-import { useCustomizationController, usePermissions } from "@rebasepro/app";
-import { copyEntityAction, deleteEntityAction, unlinkEntityAction } from "../components/common/default_entity_actions";
-import { mergeEntityActions } from "../util/entity_actions";
-import { resolveEntityAction } from "../util/resolutions";
-import { useChildViewSource } from "./useChildViewSource";
-
-export interface UseRecordActionsParams<M extends Record<string, unknown>> {
-    collection: AdminCollection<M>;
-    path: string;
-    entity?: Entity<M>;
-}
-
-/**
- * The actions you can perform *on* a record — copy, delete, and whatever the
- * collection adds — resolved against the current user's permissions.
- *
- * Extracted from the form's footer so the identity bar can own them. They are
- * not ways to leave the form, so they never belonged next to Save; putting them
- * in the bar's overflow menu is what let the footer disappear instead of
- * becoming a full-width strip holding two icon buttons.
- */
-export function useRecordActions<M extends Record<string, unknown>>({
-    collection,
-    path,
-    entity
-}: UseRecordActionsParams<M>): EntityAction[] {
-
-    const { canCreate, canDelete } = usePermissions();
-    const customizationController = useCustomizationController();
-
-    // Rows shared through a junction: the delete action here removes the link,
-    // because that is what the server does for this path.
-    const childViewSource = useChildViewSource(path);
-    const isLinkedChildView = childViewSource?.kind === "relation" && childViewSource.mode === "linked";
-
-    return useMemo((): EntityAction[] => {
-        const customEntityActions = (collection.entityActions ?? [])
-            .map(action => resolveEntityAction(action, customizationController.entityActions))
-            .filter(Boolean) as EntityAction[];
-
-        const createEnabled = canCreate(collection, path);
-        const deleteEnabled = entity ? canDelete(collection, path, entity) : false;
-        const disableActions = collection.disableDefaultActions ?? [];
-
-        const actions: EntityAction[] = [];
-        if (createEnabled && !disableActions.includes("copy"))
-            actions.push(copyEntityAction);
-        if (deleteEnabled && !disableActions.includes("delete"))
-            actions.push(isLinkedChildView ? unlinkEntityAction : deleteEntityAction);
-
-        const merged = customEntityActions.length
-            ? mergeEntityActions(actions, customEntityActions)
-            : actions;
-
-        return merged.filter(a => a.includeInForm === undefined || a.includeInForm);
-    }, [
-        canCreate,
-        canDelete,
-        collection,
-        path,
-        customizationController.entityActions?.length,
-        entity,
-        collection.disableDefaultActions,
-        isLinkedChildView
-    ]);
-}