@object-ui/app-shell 11.3.0 → 11.5.0

package/dist/preview/DraftChangesPanel.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 /**
  * ObjectUI
  * Copyright (c) 2024-present ObjectStack Inc.
@@ -11,19 +11,24 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * user commits. Lists every pending ADR-0033 draft grouped by metadata type,
  * and classifies each as NEW (no published version exists — publishing adds
  * it) or UPDATE (a published version exists — publishing overwrites it).
- * This is the review surface that turns Publish from a leap of faith into an
- * informed click; the per-item designer diff remains the deep-dive.
+ * Each entry expands into a field-level diff (objects) / changed-key summary
+ * (everything else), lazily fetched on first expand. This is the review
+ * surface that turns Publish from a leap of faith into an informed click.
  *
- * Read-only: fetches `_drafts` + per-item `/published` probes on open, and
- * never writes. Publishing stays with the caller (DraftPreviewBar / chat).
+ * Read-only by default: fetches `_drafts` + published lists on open, and
+ * never writes. When the caller passes `onPublish`, the panel additionally
+ * renders a confirm footer — review-then-publish in one surface — but the
+ * publish action itself still belongs to the caller.
  */
 import { useCallback, useEffect, useState } from 'react';
-import { FilePlus2, FilePen, Loader2 } from 'lucide-react';
-import { Badge, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, } from '@object-ui/components';
+import { ChevronDown, ChevronRight, FilePlus2, FilePen, Loader2, Rocket } from 'lucide-react';
+import { Badge, Button, Sheet, SheetContent, SheetDescription, SheetHeader, SheetTitle, } from '@object-ui/components';
 import { useObjectTranslation } from '@object-ui/i18n';
+import { diffFields } from '../views/metadata-admin/previews/object-fields-io';
 /** Pending drafts straight from the ADR-0033 `_drafts` endpoint. */
-async function listPendingDrafts() {
-    const res = await fetch('/api/v1/meta/_drafts', {
+async function listPendingDrafts(packageId) {
+    const qs = packageId ? `?packageId=${encodeURIComponent(packageId)}` : '';
+    const res = await fetch(`/api/v1/meta/_drafts${qs}`, {
         credentials: 'include',
         headers: { Accept: 'application/json' },
         cache: 'no-store',
@@ -61,15 +66,131 @@ async function publishedNamesOf(type) {
         .map((it) => (typeof it?.name === 'string' ? it.name : null))
         .filter((n) => n !== null));
 }
-export function DraftChangesPanel({ open, onOpenChange }) {
+/**
+ * Some framework reads wrap the body in a `{ type, name, item }` envelope
+ * (draft reads do; published reads return the bare body). Unwrap defensively.
+ */
+function unwrapItem(payload) {
+    if (!payload || typeof payload !== 'object')
+        return null;
+    const p = payload;
+    if (p.item && typeof p.item === 'object')
+        return p.item;
+    return p;
+}
+async function fetchItemBody(type, name, opts = {}) {
+    const params = [];
+    if (opts.draft)
+        params.push('state=draft');
+    if (opts.packageId)
+        params.push(`package=${encodeURIComponent(opts.packageId)}`);
+    const qs = params.length ? `?${params.join('&')}` : '';
+    const res = await fetch(`/api/v1/meta/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`, { credentials: 'include', headers: { Accept: 'application/json' }, cache: 'no-store' });
+    if (res.status === 404)
+        return null;
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    return unwrapItem(await res.json());
+}
+/** Stable equality for metadata values (small JSON — order-sensitive is fine). */
+function valueEqual(a, b) {
+    return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+/**
+ * What publishing this draft actually changes, computed client-side from the
+ * published body (null when the item is NEW) and the pending draft body.
+ * `fields` gets the dedicated designer diff; every other top-level key is
+ * compared wholesale — enough to answer "which parts of this item move".
+ */
+export function computeChangeDetail(published, draft) {
+    const pub = published ?? {};
+    const cur = draft ?? {};
+    let fields = null;
+    if (pub.fields != null || cur.fields != null) {
+        const d = diffFields(pub.fields, cur.fields);
+        fields = {
+            added: Object.values(d.byName)
+                .filter((e) => e.status === 'added')
+                .map((e) => e.name)
+                .sort(),
+            changed: Object.values(d.byName)
+                .filter((e) => e.status === 'changed')
+                .map((e) => ({ name: e.name, keys: e.changedKeys }))
+                .sort((a, b) => a.name.localeCompare(b.name)),
+            removed: d.removed.map((e) => e.name).sort(),
+        };
+    }
+    const keys = new Set([...Object.keys(pub), ...Object.keys(cur)]);
+    keys.delete('fields');
+    const changedKeys = [...keys]
+        .filter((k) => !valueEqual(pub[k], cur[k]))
+        .sort();
+    return { fields, changedKeys };
+}
+/**
+ * Lazily-loaded drill-in for one draft entry: published vs draft, rendered as
+ * added / changed / removed field rows plus a changed-top-level-keys strip.
+ */
+function EntryDetail({ entry }) {
+    const { t } = useObjectTranslation();
+    const [detail, setDetail] = useState(null);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        let cancelled = false;
+        (async () => {
+            try {
+                const [published, draft] = await Promise.all([
+                    // A NEW item 404s on the published read — that's data, not an error.
+                    fetchItemBody(entry.type, entry.name, { packageId: entry.packageId }),
+                    fetchItemBody(entry.type, entry.name, { draft: true, packageId: entry.packageId }),
+                ]);
+                if (!cancelled)
+                    setDetail(computeChangeDetail(published, draft));
+            }
+            catch (e) {
+                if (!cancelled)
+                    setError(e.message);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [entry.type, entry.name, entry.packageId]);
+    if (error) {
+        return (_jsxs("p", { className: "px-2 py-1 text-xs text-destructive", children: [t('preview.changes.detailLoadFailed', { defaultValue: 'Could not load change detail:' }), ' ', error] }));
+    }
+    if (!detail) {
+        return (_jsxs("p", { className: "flex items-center gap-1.5 px-2 py-1 text-xs text-muted-foreground", children: [_jsx(Loader2, { className: "h-3 w-3 animate-spin" }), t('preview.changes.detailLoading', { defaultValue: 'Loading detail…' })] }));
+    }
+    const { fields, changedKeys } = detail;
+    const hasFieldRows = !!fields && (fields.added.length > 0 || fields.changed.length > 0 || fields.removed.length > 0);
+    if (!hasFieldRows && changedKeys.length === 0) {
+        return (_jsx("p", { className: "px-2 py-1 text-xs text-muted-foreground", children: t('preview.changes.detailNone', {
+                defaultValue: 'No differences detected — the draft matches the published version.',
+            }) }));
+    }
+    return (_jsxs("div", { className: "flex flex-col gap-0.5 px-2 py-1", "data-testid": "draft-entry-detail", children: [fields?.added.map((name) => (_jsxs("p", { className: "font-mono text-xs text-emerald-700 dark:text-emerald-400", children: ["+ ", name] }, `+${name}`))), fields?.changed.map((f) => (_jsxs("p", { className: "font-mono text-xs text-amber-700 dark:text-amber-400", children: ["~ ", f.name, f.keys.length > 0 && _jsxs("span", { className: "text-muted-foreground", children: [" \u00B7 ", f.keys.join(', ')] })] }, `~${f.name}`))), fields?.removed.map((name) => (_jsxs("p", { className: "font-mono text-xs text-red-700 line-through dark:text-red-400", children: ["\u2212 ", name] }, `-${name}`))), changedKeys.length > 0 && (_jsxs("p", { className: "text-xs text-muted-foreground", children: [t('preview.changes.detailChangedKeys', { defaultValue: 'Also changed:' }), ' ', _jsx("span", { className: "font-mono", children: changedKeys.join(', ') })] }))] }));
+}
+export function DraftChangesPanel({ open, onOpenChange, packageId, onPublish, publishing = false, }) {
     const { t } = useObjectTranslation();
     const [entries, setEntries] = useState(null);
     const [error, setError] = useState(null);
+    const [expanded, setExpanded] = useState(new Set());
+    const toggleExpanded = useCallback((key) => {
+        setExpanded((prev) => {
+            const next = new Set(prev);
+            if (next.has(key))
+                next.delete(key);
+            else
+                next.add(key);
+            return next;
+        });
+    }, []);
     const load = useCallback(async () => {
         setEntries(null);
         setError(null);
         try {
-            const drafts = await listPendingDrafts();
+            const drafts = await listPendingDrafts(packageId);
             setEntries(drafts);
             // Classify new-vs-update per TYPE: one published-list read covers every
             // draft of that type. A type whose read fails stays unclassified
@@ -93,7 +214,7 @@ export function DraftChangesPanel({ open, onOpenChange }) {
         catch (e) {
             setError(e.message);
         }
-    }, []);
+    }, [packageId]);
     useEffect(() => {
         if (open)
             void load();
@@ -104,11 +225,18 @@ export function DraftChangesPanel({ open, onOpenChange }) {
         bucket.push(entry);
         byType.set(entry.type, bucket);
     }
-    return (_jsx(Sheet, { open: open, onOpenChange: onOpenChange, children: _jsxs(SheetContent, { side: "right", className: "w-[420px] sm:max-w-[420px]", "data-testid": "draft-changes-panel", children: [_jsxs(SheetHeader, { children: [_jsx(SheetTitle, { children: t('preview.changes.title', { defaultValue: 'Pending changes' }) }), _jsx(SheetDescription, { children: t('preview.changes.description', {
+    return (_jsx(Sheet, { open: open, onOpenChange: onOpenChange, children: _jsxs(SheetContent, { side: "right", className: "flex w-[420px] flex-col sm:max-w-[420px]", "data-testid": "draft-changes-panel", children: [_jsxs(SheetHeader, { children: [_jsx(SheetTitle, { children: t('preview.changes.title', { defaultValue: 'Pending changes' }) }), _jsx(SheetDescription, { children: t('preview.changes.description', {
                                 defaultValue: 'What publishing will change. New items are added; updates overwrite the live version.',
-                            }) })] }), _jsx("div", { className: "mt-4 flex flex-col gap-4 overflow-y-auto px-4 pb-6", children: error ? (_jsxs("p", { className: "text-sm text-destructive", children: [t('preview.changes.loadFailed', { defaultValue: 'Could not load pending changes:' }), ' ', error] })) : entries === null ? (_jsxs("div", { className: "flex items-center gap-2 text-sm text-muted-foreground", children: [_jsx(Loader2, { className: "h-4 w-4 animate-spin" }), t('preview.changes.loading', { defaultValue: 'Loading pending changes…' })] })) : entries.length === 0 ? (_jsx("p", { className: "text-sm text-muted-foreground", children: t('preview.changes.empty', { defaultValue: 'Nothing pending — every draft has been published.' }) })) : ([...byType.entries()].map(([type, items]) => (_jsxs("div", { children: [_jsxs("h4", { className: "mb-1.5 text-xs font-semibold uppercase tracking-wide text-muted-foreground", children: [type, " \u00B7 ", items.length] }), _jsx("ul", { className: "flex flex-col gap-1", children: items.map((entry) => (_jsxs("li", { className: "flex items-center gap-2 rounded-md border px-2.5 py-1.5 text-sm", children: [entry.kind === 'new' ? (_jsx(FilePlus2, { className: "h-3.5 w-3.5 shrink-0 text-emerald-600" })) : entry.kind === 'update' ? (_jsx(FilePen, { className: "h-3.5 w-3.5 shrink-0 text-amber-600" })) : (_jsx(Loader2, { className: "h-3.5 w-3.5 shrink-0 animate-spin text-muted-foreground" })), _jsx("span", { className: "min-w-0 flex-1 truncate font-mono text-xs", children: entry.name }), entry.kind ? (_jsx(Badge, { variant: "outline", className: entry.kind === 'new'
-                                                ? 'border-emerald-200 bg-emerald-50 text-emerald-700'
-                                                : 'border-amber-200 bg-amber-50 text-amber-700', children: entry.kind === 'new'
-                                                ? t('preview.changes.kindNew', { defaultValue: 'New' })
-                                                : t('preview.changes.kindUpdate', { defaultValue: 'Update' }) })) : null] }, `${entry.type}:${entry.name}`))) })] }, type)))) })] }) }));
+                            }) })] }), _jsx("div", { className: "mt-4 flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto px-4 pb-6", children: error ? (_jsxs("p", { className: "text-sm text-destructive", children: [t('preview.changes.loadFailed', { defaultValue: 'Could not load pending changes:' }), ' ', error] })) : entries === null ? (_jsxs("div", { className: "flex items-center gap-2 text-sm text-muted-foreground", children: [_jsx(Loader2, { className: "h-4 w-4 animate-spin" }), t('preview.changes.loading', { defaultValue: 'Loading pending changes…' })] })) : entries.length === 0 ? (_jsx("p", { className: "text-sm text-muted-foreground", children: t('preview.changes.empty', { defaultValue: 'Nothing pending — every draft has been published.' }) })) : ([...byType.entries()].map(([type, items]) => (_jsxs("div", { children: [_jsxs("h4", { className: "mb-1.5 text-xs font-semibold uppercase tracking-wide text-muted-foreground", children: [type, " \u00B7 ", items.length] }), _jsx("ul", { className: "flex flex-col gap-1", children: items.map((entry) => {
+                                    const key = `${entry.type}:${entry.name}`;
+                                    const isExpanded = expanded.has(key);
+                                    return (_jsxs("li", { className: "rounded-md border text-sm", children: [_jsxs("button", { type: "button", onClick: () => toggleExpanded(key), "aria-expanded": isExpanded, className: "flex w-full items-center gap-2 px-2.5 py-1.5 text-left hover:bg-muted/50", "data-testid": "draft-entry-toggle", children: [isExpanded ? (_jsx(ChevronDown, { className: "h-3 w-3 shrink-0 text-muted-foreground" })) : (_jsx(ChevronRight, { className: "h-3 w-3 shrink-0 text-muted-foreground" })), entry.kind === 'new' ? (_jsx(FilePlus2, { className: "h-3.5 w-3.5 shrink-0 text-emerald-600" })) : entry.kind === 'update' ? (_jsx(FilePen, { className: "h-3.5 w-3.5 shrink-0 text-amber-600" })) : (_jsx(Loader2, { className: "h-3.5 w-3.5 shrink-0 animate-spin text-muted-foreground" })), _jsx("span", { className: "min-w-0 flex-1 truncate font-mono text-xs", children: entry.name }), entry.kind ? (_jsx(Badge, { variant: "outline", className: entry.kind === 'new'
+                                                            ? 'border-emerald-200 bg-emerald-50 text-emerald-700'
+                                                            : 'border-amber-200 bg-amber-50 text-amber-700', children: entry.kind === 'new'
+                                                            ? t('preview.changes.kindNew', { defaultValue: 'New' })
+                                                            : t('preview.changes.kindUpdate', { defaultValue: 'Update' }) })) : null] }), isExpanded && (_jsx("div", { className: "border-t bg-muted/20", children: _jsx(EntryDetail, { entry: entry }) }))] }, key));
+                                }) })] }, type)))) }), onPublish && (entries?.length ?? 0) > 0 && !error && (_jsxs("div", { className: "mt-auto flex flex-col gap-2 border-t px-4 py-3", children: [_jsx("p", { className: "text-xs text-muted-foreground", children: t('preview.changes.confirmNote', {
+                                count: entries.length,
+                                defaultValue: 'Publishing releases all {{count}} pending drafts of this package atomically.',
+                            }) }), _jsxs(Button, { size: "sm", onClick: () => void onPublish(), disabled: publishing, "data-testid": "draft-changes-publish", children: [publishing ? (_jsx(Loader2, { className: "mr-1.5 h-3.5 w-3.5 animate-spin" })) : (_jsx(Rocket, { className: "mr-1.5 h-3.5 w-3.5" })), t('preview.changes.publishConfirm', { defaultValue: 'Publish all' })] })] }))] }) }));
 }

package/dist/urlParams.d.ts

@@ -0,0 +1,68 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * urlParams — the single registry of RESERVED console URL query params
+ * (objectui#2269 P3; ADR-0054 C3 "URL-addressable state").
+ *
+ * These params form the console's cross-route URL contract: they are read
+ * and written by app-shell chrome (overlays, record surfaces, tabs) and must
+ * never be repurposed by a page/view for something else. Every reader/writer
+ * imports the constant from here — no string literals — so the contract has
+ * ONE definition, collisions are caught at review time, and an AI author
+ * (north star: all metadata is AI-authored) has a single place to learn it.
+ *
+ * | Param       | Meaning                                        | History      |
+ * |-------------|------------------------------------------------|--------------|
+ * | `recordId`  | Record detail DRAWER over a list (light        | push (open)  |
+ * |             | objects; heavy ones use the `/record/:id`      |              |
+ * |             | route instead). URL is the drawer's source of  |              |
+ * |             | truth.                                         |              |
+ * | `form`      | The global record-form overlay: `new` = create,|              |
+ * |             | a record id = edit (framework#2604 D1/D2).     | push (open), |
+ * |             | Back closes the overlay.                       | replace (close) |
+ * | `formObject`| Child-task override for `form`: the object the |              |
+ * |             | overlay edits when it is NOT the route's       | with `form`  |
+ * |             | object (subtable child over a parent detail,   |              |
+ * |             | framework#2604 D3).                            |              |
+ * | `formLink`  | `"<fkField>:<parentId>"` — create-mode parent  |              |
+ * |             | pre-link for a child task; refresh-safe.       | with `form`  |
+ * | `tab`       | Active record-detail tab (stable semantic      | replace      |
+ * |             | values: `details` / `related:<child>` /        |              |
+ * |             | `related` / `activity` / `history`,            |              |
+ * |             | objectui#2257). Never stacks history.          |              |
+ * | `palette`   | Command palette overlay (alias `cmdk`).        | replace      |
+ * | `shortcuts` | Keyboard-shortcuts dialog overlay.             | replace      |
+ *
+ * Push-vs-replace rule of thumb: an overlay the user OPENED (form, drawer)
+ * pushes one entry so browser Back closes it; passive state that tracks an
+ * in-page selection (tab) or transient chrome (palette) replaces, so Back
+ * never pages through it.
+ *
+ * Page-scoped params (`q`, `limit`, `offset`, `view`, `type`, `review`,
+ * `package`, …) belong to their page's own contract and are NOT reserved
+ * here — but they must not collide with the names above.
+ */
+/** Record detail drawer over a list (`?recordId=<id>`). */
+export declare const RECORD_DRAWER_PARAM = "recordId";
+/** Global record-form overlay: `new` | `<recordId>` (framework#2604). */
+export declare const RECORD_FORM_PARAM = "form";
+/** Child-task object override for the record-form overlay (#2604 D3). */
+export declare const RECORD_FORM_OBJECT_PARAM = "formObject";
+/** Child-task parent pre-link `"<fkField>:<parentId>"` (#2604 D3). */
+export declare const RECORD_FORM_LINK_PARAM = "formLink";
+/** Active record-detail tab (objectui#2257; stable semantic values). */
+export declare const RECORD_DETAIL_TAB_PARAM = "tab";
+/** Command palette overlay (ADR-0054 Phase 1; alias `cmdk`). */
+export declare const COMMAND_PALETTE_PARAM = "palette";
+/** Keyboard-shortcuts dialog overlay. */
+export declare const KEYBOARD_SHORTCUTS_PARAM = "shortcuts";
+/**
+ * All reserved params, for collision checks (e.g. a lint or a dev-time
+ * assertion that a page-scoped param doesn't shadow the console contract).
+ */
+export declare const RESERVED_URL_PARAMS: readonly string[];

package/dist/urlParams.js

@@ -0,0 +1,76 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * urlParams — the single registry of RESERVED console URL query params
+ * (objectui#2269 P3; ADR-0054 C3 "URL-addressable state").
+ *
+ * These params form the console's cross-route URL contract: they are read
+ * and written by app-shell chrome (overlays, record surfaces, tabs) and must
+ * never be repurposed by a page/view for something else. Every reader/writer
+ * imports the constant from here — no string literals — so the contract has
+ * ONE definition, collisions are caught at review time, and an AI author
+ * (north star: all metadata is AI-authored) has a single place to learn it.
+ *
+ * | Param       | Meaning                                        | History      |
+ * |-------------|------------------------------------------------|--------------|
+ * | `recordId`  | Record detail DRAWER over a list (light        | push (open)  |
+ * |             | objects; heavy ones use the `/record/:id`      |              |
+ * |             | route instead). URL is the drawer's source of  |              |
+ * |             | truth.                                         |              |
+ * | `form`      | The global record-form overlay: `new` = create,|              |
+ * |             | a record id = edit (framework#2604 D1/D2).     | push (open), |
+ * |             | Back closes the overlay.                       | replace (close) |
+ * | `formObject`| Child-task override for `form`: the object the |              |
+ * |             | overlay edits when it is NOT the route's       | with `form`  |
+ * |             | object (subtable child over a parent detail,   |              |
+ * |             | framework#2604 D3).                            |              |
+ * | `formLink`  | `"<fkField>:<parentId>"` — create-mode parent  |              |
+ * |             | pre-link for a child task; refresh-safe.       | with `form`  |
+ * | `tab`       | Active record-detail tab (stable semantic      | replace      |
+ * |             | values: `details` / `related:<child>` /        |              |
+ * |             | `related` / `activity` / `history`,            |              |
+ * |             | objectui#2257). Never stacks history.          |              |
+ * | `palette`   | Command palette overlay (alias `cmdk`).        | replace      |
+ * | `shortcuts` | Keyboard-shortcuts dialog overlay.             | replace      |
+ *
+ * Push-vs-replace rule of thumb: an overlay the user OPENED (form, drawer)
+ * pushes one entry so browser Back closes it; passive state that tracks an
+ * in-page selection (tab) or transient chrome (palette) replaces, so Back
+ * never pages through it.
+ *
+ * Page-scoped params (`q`, `limit`, `offset`, `view`, `type`, `review`,
+ * `package`, …) belong to their page's own contract and are NOT reserved
+ * here — but they must not collide with the names above.
+ */
+/** Record detail drawer over a list (`?recordId=<id>`). */
+export const RECORD_DRAWER_PARAM = 'recordId';
+/** Global record-form overlay: `new` | `<recordId>` (framework#2604). */
+export const RECORD_FORM_PARAM = 'form';
+/** Child-task object override for the record-form overlay (#2604 D3). */
+export const RECORD_FORM_OBJECT_PARAM = 'formObject';
+/** Child-task parent pre-link `"<fkField>:<parentId>"` (#2604 D3). */
+export const RECORD_FORM_LINK_PARAM = 'formLink';
+/** Active record-detail tab (objectui#2257; stable semantic values). */
+export const RECORD_DETAIL_TAB_PARAM = 'tab';
+/** Command palette overlay (ADR-0054 Phase 1; alias `cmdk`). */
+export const COMMAND_PALETTE_PARAM = 'palette';
+/** Keyboard-shortcuts dialog overlay. */
+export const KEYBOARD_SHORTCUTS_PARAM = 'shortcuts';
+/**
+ * All reserved params, for collision checks (e.g. a lint or a dev-time
+ * assertion that a page-scoped param doesn't shadow the console contract).
+ */
+export const RESERVED_URL_PARAMS = [
+    RECORD_DRAWER_PARAM,
+    RECORD_FORM_PARAM,
+    RECORD_FORM_OBJECT_PARAM,
+    RECORD_FORM_LINK_PARAM,
+    RECORD_DETAIL_TAB_PARAM,
+    COMMAND_PALETTE_PARAM,
+    KEYBOARD_SHORTCUTS_PARAM,
+];

package/dist/utils/appRoute.d.ts

@@ -18,4 +18,19 @@ type AppLike = {
 } & Record<string, unknown>;
 export declare function appRouteSegment(app: AppLike | null | undefined): string | undefined;
 export declare function matchAppBySegment<T extends AppLike>(apps: readonly T[] | null | undefined, seg: string | null | undefined): T | undefined;
+/**
+ * App → Studio reverse bridge (ADR-0080). Resolves a running app to its owning
+ * package's design surface (`/studio/:packageId/data`), or `null` when there is
+ * nothing to open:
+ * - the viewer is not a workspace admin (designing mutates shared package
+ *   metadata, so the entry point is admin-only — mirrors the runtime editors);
+ * - the app has no owning package (runtime/DB apps), or its container is the
+ *   DB-authored `sys_metadata` pseudo-package, which is not a package the
+ *   Studio design surface can open.
+ *
+ * Writability of the target package is NOT checked here — the ADR-0070 D4 gate
+ * stays the server-side authority, and the Studio surface itself renders
+ * read-only packages as browse-only.
+ */
+export declare function appStudioDesignPath(app: AppLike | null | undefined, isWorkspaceAdmin: boolean): string | null;
 export {};

package/dist/utils/appRoute.js

@@ -23,3 +23,25 @@ export function matchAppBySegment(apps, seg) {
         return undefined;
     return apps.find((a) => a?._packageId === seg) ?? apps.find((a) => a?.name === seg);
 }
+/**
+ * App → Studio reverse bridge (ADR-0080). Resolves a running app to its owning
+ * package's design surface (`/studio/:packageId/data`), or `null` when there is
+ * nothing to open:
+ * - the viewer is not a workspace admin (designing mutates shared package
+ *   metadata, so the entry point is admin-only — mirrors the runtime editors);
+ * - the app has no owning package (runtime/DB apps), or its container is the
+ *   DB-authored `sys_metadata` pseudo-package, which is not a package the
+ *   Studio design surface can open.
+ *
+ * Writability of the target package is NOT checked here — the ADR-0070 D4 gate
+ * stays the server-side authority, and the Studio surface itself renders
+ * read-only packages as browse-only.
+ */
+export function appStudioDesignPath(app, isWorkspaceAdmin) {
+    if (!isWorkspaceAdmin)
+        return null;
+    const packageId = app?._packageId;
+    if (typeof packageId !== 'string' || !packageId || packageId === 'sys_metadata')
+        return null;
+    return `/studio/${encodeURIComponent(packageId)}/data`;
+}

package/dist/utils/deriveRelatedLists.d.ts

@@ -9,20 +9,29 @@
  *
  * This helper scans every object for fields whose `reference`/`reference_to`
  * points back at the parent object and produces one related-list descriptor per
- * child collection. The detail page (`RecordDetailView`) feeds these into the
+ * eligible FK. The detail page (`RecordDetailView`) feeds these into the
  * `record:related_list` renderers (and the legacy `DetailView.related`).
  *
  * Rules (kept in lockstep with the relationship-level `relatedList` spec flag):
  *   - Owned children (`master_detail`) and `lookup` children are SHOWN by
  *     default. Set `relatedList: false` on the FK field to suppress a noisy
- *     association/audit link.
+ *     association/audit link; set `relatedList: 'primary'` to mark a CORE
+ *     relationship — the detail page promotes it to its own tab (the tab-vs-
+ *     Related split is decided downstream in `buildDefaultTabs`).
  *   - `relatedListTitle` / `relatedListColumns` on the FK field override the
- *     derived title / columns.
+ *     derived title / columns (columns default to the child object's own list
+ *     columns when omitted — resolved by the renderer).
  *   - Audit FKs (`created_by` / `updated_by` / `owner_id`) are skipped — they
  *     exist on virtually every object and would balloon the detail page into
  *     dozens of duplicate cards.
- *   - One related list per child object (deduped by child object name): the
- *     first non-audit, non-suppressed FK wins.
+ *   - ONE related list per eligible FK. A child may point at the parent through
+ *     MORE THAN ONE relationship (e.g. `opportunity.primary_account` +
+ *     `opportunity.partner_account`); each surfaces as its own list. When a
+ *     child appears more than once and gave no explicit `relatedListTitle`, the
+ *     FK's label is suffixed to disambiguate ("Opportunity · Partner Account").
+ *   - Self-references are allowed (e.g. `account.parent_account` → `account`):
+ *     the parent record lists the records whose self-FK points back at it
+ *     ("Child Accounts"). Suppress with `relatedList: false` if unwanted.
  *   - Owned (`master_detail`) children are ordered before plain `lookup`
  *     children, preserving discovery order within each group.
  */
@@ -39,6 +48,12 @@ export interface DerivedRelatedList {
     columns?: any[];
     /** True when the child→parent link is a `master_detail` (owned) relationship. */
     isOwned: boolean;
+    /**
+     * True when the FK declares `relatedList: 'primary'`. A prominence hint
+     * (ADR-0085): the detail page promotes this relationship to its OWN tab,
+     * while non-primary lists collapse into a single "Related" tab.
+     */
+    isPrimary: boolean;
 }
 interface ObjectLike {
     name?: string;

package/dist/utils/deriveRelatedLists.js

@@ -9,20 +9,29 @@
  *
  * This helper scans every object for fields whose `reference`/`reference_to`
  * points back at the parent object and produces one related-list descriptor per
- * child collection. The detail page (`RecordDetailView`) feeds these into the
+ * eligible FK. The detail page (`RecordDetailView`) feeds these into the
  * `record:related_list` renderers (and the legacy `DetailView.related`).
  *
  * Rules (kept in lockstep with the relationship-level `relatedList` spec flag):
  *   - Owned children (`master_detail`) and `lookup` children are SHOWN by
  *     default. Set `relatedList: false` on the FK field to suppress a noisy
- *     association/audit link.
+ *     association/audit link; set `relatedList: 'primary'` to mark a CORE
+ *     relationship — the detail page promotes it to its own tab (the tab-vs-
+ *     Related split is decided downstream in `buildDefaultTabs`).
  *   - `relatedListTitle` / `relatedListColumns` on the FK field override the
- *     derived title / columns.
+ *     derived title / columns (columns default to the child object's own list
+ *     columns when omitted — resolved by the renderer).
  *   - Audit FKs (`created_by` / `updated_by` / `owner_id`) are skipped — they
  *     exist on virtually every object and would balloon the detail page into
  *     dozens of duplicate cards.
- *   - One related list per child object (deduped by child object name): the
- *     first non-audit, non-suppressed FK wins.
+ *   - ONE related list per eligible FK. A child may point at the parent through
+ *     MORE THAN ONE relationship (e.g. `opportunity.primary_account` +
+ *     `opportunity.partner_account`); each surfaces as its own list. When a
+ *     child appears more than once and gave no explicit `relatedListTitle`, the
+ *     FK's label is suffixed to disambiguate ("Opportunity · Partner Account").
+ *   - Self-references are allowed (e.g. `account.parent_account` → `account`):
+ *     the parent record lists the records whose self-FK points back at it
+ *     ("Child Accounts"). Suppress with `relatedList: false` if unwanted.
  *   - Owned (`master_detail`) children are ordered before plain `lookup`
  *     children, preserving discovery order within each group.
  */
@@ -50,9 +59,8 @@ export function deriveRelatedLists(objectDef, objects) {
     const parentName = objectDef.name;
     const owned = [];
     const referenced = [];
-    const seenChild = new Set();
     for (const child of objects) {
-        if (!child?.name || child.name === parentName)
+        if (!child?.name)
             continue;
         for (const [fieldName, fieldDef] of fieldEntries(child.fields)) {
             if (!fieldDef)
@@ -67,15 +75,13 @@ export function deriveRelatedLists(objectDef, objects) {
             // Explicit opt-out lives on the relationship.
             if (fieldDef.relatedList === false)
                 continue;
-            // One related list per child object — the first eligible FK wins.
-            if (seenChild.has(child.name))
-                continue;
-            seenChild.add(child.name);
             const entry = {
                 childObject: child.name,
                 childLabel: child.label || child.name,
                 referenceField: fieldName,
                 isOwned: type === 'master_detail',
+                isPrimary: fieldDef.relatedList === 'primary',
+                _fkLabel: (typeof fieldDef.label === 'string' && fieldDef.label) || fieldName,
                 ...(typeof fieldDef.relatedListTitle === 'string' && fieldDef.relatedListTitle
                     ? { title: fieldDef.relatedListTitle }
                     : {}),
@@ -83,9 +89,21 @@ export function deriveRelatedLists(objectDef, objects) {
                     ? { columns: fieldDef.relatedListColumns }
                     : {}),
             };
+            // NO `break`: a child object may reference this parent through several FKs.
             (entry.isOwned ? owned : referenced).push(entry);
-            break; // move on to the next child object
         }
     }
-    return [...owned, ...referenced];
+    const all = [...owned, ...referenced];
+    // Multi-FK disambiguation: when a child object points here through more than
+    // one relationship and gave no explicit title, suffix the FK label so the two
+    // lists are distinguishable (e.g. "Opportunity · Partner Account").
+    const counts = {};
+    for (const r of all)
+        counts[r.childObject] = (counts[r.childObject] || 0) + 1;
+    return all.map(({ _fkLabel, ...rest }) => {
+        if (!rest.title && counts[rest.childObject] > 1) {
+            return { ...rest, title: `${rest.childLabel} · ${_fkLabel}` };
+        }
+        return rest;
+    });
 }

package/dist/utils/index.d.ts

@@ -8,7 +8,7 @@ export type { ObjectDefinitionForNavigation, RecordFormTarget, ObjectDefinitionF
 export { deriveRelatedLists } from './deriveRelatedLists';
 export type { DerivedRelatedList } from './deriveRelatedLists';
 export { preferLocal } from './preferLocal';
-export { appRouteSegment, matchAppBySegment } from './appRoute';
+export { appRouteSegment, matchAppBySegment, appStudioDesignPath } from './appRoute';
 /**
  * Resolves an I18nLabel to a plain string.
  * I18nLabel can be either a string or an object { key, defaultValue?, params? }.

package/dist/utils/index.js

@@ -12,7 +12,7 @@ formatTitleTemplate as formatRecordTitle, } from '@object-ui/core';
 export { resolveRecordFormTarget, resolveFormViewLayout, } from './recordFormNavigation';
 export { deriveRelatedLists } from './deriveRelatedLists';
 export { preferLocal } from './preferLocal';
-export { appRouteSegment, matchAppBySegment } from './appRoute';
+export { appRouteSegment, matchAppBySegment, appStudioDesignPath } from './appRoute';
 /**
  * Resolves an I18nLabel to a plain string.
  * I18nLabel can be either a string or an object { key, defaultValue?, params? }.

package/dist/utils/pageTabsUrlSync.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * pageTabsUrlSync — make a record page's `page:tabs` node URL-aware
+ * (objectui#2257, ADR-0054 C3 "URL-addressable state").
+ *
+ * The active detail tab is user state that must SURVIVE the page subtree
+ * remounting — which happens for real on every `refreshKey`-style save
+ * refresh (and, in dev StrictMode, on any URL search change). An
+ * uncontrolled Radix `defaultValue` loses it; the URL keeps it.
+ *
+ * This helper walks a page schema tree and returns a NEW tree in which every
+ * `page:tabs` node carries the host-provided `defaultTab` (the value read
+ * from `?tab=`) and `onTabChange` (writes `?tab=` back, with `replace`). It
+ * never mutates the input — authored/assigned page schemas may be shared or
+ * memoized objects.
+ *
+ * Only container keys are traversed (`regions` / `components` / `children`);
+ * `page:tabs`' own `items` are its content, not a container to recurse into.
+ */
+export interface PageTabsUrlSyncInject {
+    /** Initial active tab (from `?tab=`); ignored by the renderer if it names no tab. */
+    defaultTab?: string;
+    /** Called by the renderer on every tab switch (host writes `?tab=`). */
+    onTabChange?: (value: string) => void;
+}
+export declare function withPageTabsUrlSync<T>(node: T, inject: PageTabsUrlSyncInject): T;

package/dist/utils/pageTabsUrlSync.js

@@ -0,0 +1,43 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const CONTAINER_KEYS = ['regions', 'components', 'children'];
+export function withPageTabsUrlSync(node, inject) {
+    if (Array.isArray(node)) {
+        let outArr = null;
+        node.forEach((n, i) => {
+            const next = withPageTabsUrlSync(n, inject);
+            if (next !== n) {
+                outArr = outArr ?? node.slice();
+                outArr[i] = next;
+            }
+        });
+        return (outArr ?? node);
+    }
+    if (!node || typeof node !== 'object')
+        return node;
+    const rec = node;
+    let out = null;
+    if (rec.type === 'page:tabs') {
+        out = { ...rec };
+        if (inject.defaultTab !== undefined)
+            out.defaultTab = inject.defaultTab;
+        if (inject.onTabChange)
+            out.onTabChange = inject.onTabChange;
+    }
+    for (const key of CONTAINER_KEYS) {
+        const child = (out ?? rec)[key];
+        if (child === undefined || child === null)
+            continue;
+        const next = withPageTabsUrlSync(child, inject);
+        if (next !== child) {
+            out = out ?? { ...rec };
+            out[key] = next;
+        }
+    }
+    return (out ?? node);
+}