@rebasepro/cli 0.5.0 → 0.6.1

package/skills/rebase-admin/SKILL.md

@@ -0,0 +1,710 @@
+---
+name: rebase-admin
+description: Guide for navigating the Rebase admin CMS, opening entities in side drawers, building URLs, embedding collection panels, using the collection registry, and programmatic navigation. Use this skill when an agent or user needs to navigate to a collection view, open an entity in the side panel/drawer, build admin URLs, embed a collection inside a custom page, use the entity selection dialog, or access CMS-specific controllers.
+---
+
+# Rebase Admin (`@rebasepro/admin`)
+
+The `@rebasepro/admin` package provides the CMS layer for Rebase. It handles collection views, entity editing, navigation, side panels (drawers), URL routing, breadcrumbs, and the full CMS context. This skill covers the **programmatic APIs** for navigating and interacting with the admin.
+
+> **IMPORTANT FOR AGENTS:** All hooks in this skill must be called **inside** the `<RebaseShell>` component tree. They rely on React contexts provided by `<RebaseNavigation>`, `<SideEntityProvider>`, and `<RebaseRouteDefs>`.
+
+## Quick Reference — Common Tasks
+
+| Task | Hook / Component | Package |
+|------|-----------------|---------|
+| Open entity in side drawer | `useSideEntityController()` | `@rebasepro/admin` |
+| Navigate to a collection view | `useUrlController()` | `@rebasepro/admin` |
+| Look up a collection by slug | `useCollectionRegistryController()` | `@rebasepro/admin` |
+| Embed a collection in a custom page | `<CollectionPanel>` | `@rebasepro/admin` |
+| Open an entity selection dialog | `useEntitySelectionDialog()` | `@rebasepro/admin` |
+| Open a custom side dialog | `useSideDialogsController()` | `@rebasepro/admin` |
+| Set breadcrumbs | `useBreadcrumbsController()` | `@rebasepro/admin` |
+| Access full CMS context | `useCMSContext()` | `@rebasepro/admin` |
+| Access navigation state & views | `useNavigationStateController()` | `@rebasepro/admin` |
+
+---
+
+## 1. Opening Entities in the Side Drawer
+
+Use `useSideEntityController()` to open, replace, or close entity side panels (the sliding drawer that shows entity forms).
+
+```typescript
+import { useSideEntityController } from "@rebasepro/admin";
+```
+
+### SideEntityController Interface
+
+```typescript
+interface SideEntityController {
+    /** Close the last (topmost) panel */
+    close: () => void;
+
+    /** Open a new entity side panel */
+    open: <M extends Record<string, unknown>>(props: EntitySidePanelProps<M>) => void;
+
+    /** Replace the last open panel with a new one */
+    replace: <M extends Record<string, unknown>>(props: EntitySidePanelProps<M>) => void;
+}
+```
+
+### EntitySidePanelProps
+
+```typescript
+interface EntitySidePanelProps<M extends Record<string, unknown> = Record<string, unknown>> {
+    /** Absolute path of the entity's collection (e.g. "products") */
+    path: string;
+
+    /** ID of the entity. Omit to create a new entity. */
+    entityId?: string | number;
+
+    /** Set to true to create a copy of an existing entity */
+    copy?: boolean;
+
+    /** Open with a specific sub-collection tab selected */
+    selectedTab?: string;
+
+    /** Override the width of the form panel (e.g. "600px") */
+    width?: number | string;
+
+    /** Explicit collection config (auto-resolved from navigation if omitted) */
+    collection?: EntityCollection<M>;
+
+    /** Whether to update the browser URL when opening (default: true) */
+    updateUrl?: boolean;
+
+    /** Callback when the entity is saved/updated */
+    onUpdate?: (params: { entity: Entity<M> }) => void;
+
+    /** Callback when the panel is closed */
+    onClose?: () => void;
+
+    /** Close the panel automatically after saving */
+    closeOnSave?: boolean;
+
+    /** Override form properties */
+    formProps?: Record<string, unknown>;
+
+    /** Show a full-screen toggle button */
+    allowFullScreen?: boolean;
+
+    /** Pre-populate form values when creating a new entity (only when entityId is not set) */
+    defaultValues?: Partial<M>;
+}
+```
+
+### Examples
+
+**Open an existing entity for editing:**
+```tsx
+const sideEntityController = useSideEntityController();
+
+// Open the product with ID "abc123" in the side drawer
+sideEntityController.open({
+    path: "products",
+    entityId: "abc123"
+});
+```
+
+**Create a new entity with pre-filled values:**
+```tsx
+sideEntityController.open({
+    path: "products",
+    defaultValues: {
+        name: "New Product",
+        status: "draft"
+    }
+});
+```
+
+**Open with a callback on save:**
+```tsx
+sideEntityController.open({
+    path: "orders",
+    entityId: orderId,
+    closeOnSave: true,
+    onUpdate: ({ entity }) => {
+        console.log("Saved:", entity.id, entity.values);
+    }
+});
+```
+
+**Replace the current panel (instead of stacking):**
+```tsx
+sideEntityController.replace({
+    path: "clients",
+    entityId: "xyz789"
+});
+```
+
+---
+
+## 2. Navigating to Collection Views
+
+Use `useUrlController()` to build URLs and navigate programmatically within the admin.
+
+```typescript
+import { useUrlController } from "@rebasepro/admin";
+```
+
+### UrlController Interface
+
+```typescript
+type UrlController = {
+    /** Base path for the CMS (default: "/") */
+    basePath: string;
+
+    /** Base path for collection routes (default: "/c") */
+    baseCollectionPath: string;
+
+    /** Convert a URL path to a data path: "/c/products" → "products" */
+    urlPathToDataPath: (cmsPath: string) => string;
+
+    /** Base URL for the home screen */
+    homeUrl: string;
+
+    /** Check if a URL path belongs to a collection */
+    isUrlCollectionPath: (urlPath: string) => boolean;
+
+    /** Build a URL for a collection: "products" → "/c/products" */
+    buildUrlCollectionPath: (path: string) => string;
+
+    /** Build a URL for a custom view or app path */
+    buildAppUrlPath: (path: string) => string;
+
+    /** Resolve collection IDs in a path to database paths */
+    resolveDatabasePathsFrom: (path: string) => string;
+
+    /** Navigate to a route (wraps react-router's navigate) */
+    navigate: (to: string, options?: NavigateOptions) => void;
+};
+```
+
+### Examples
+
+**Navigate to a collection view:**
+```tsx
+const urlController = useUrlController();
+
+// Navigate to the "products" collection
+const url = urlController.buildUrlCollectionPath("products");
+urlController.navigate(url);
+// This navigates to "/c/products"
+```
+
+**Navigate to a specific entity within a collection:**
+```tsx
+const url = urlController.buildUrlCollectionPath("products/abc123");
+urlController.navigate(url);
+// This navigates to "/c/products/abc123"
+```
+
+**Navigate to a custom view:**
+```tsx
+const url = urlController.buildAppUrlPath("my-dashboard");
+urlController.navigate(url);
+```
+
+**Navigate and replace history (no back button):**
+```tsx
+urlController.navigate(
+    urlController.buildUrlCollectionPath("orders"),
+    { replace: true }
+);
+```
+
+**Navigate to home:**
+```tsx
+urlController.navigate(urlController.homeUrl);
+```
+
+> **IMPORTANT FOR AGENTS:** The URL structure is `basePath + baseCollectionPath + "/" + slug`. By default this produces `/c/products`. Use `buildUrlCollectionPath()` instead of manually constructing URLs.
+
+---
+
+## 3. Collection Registry
+
+Use `useCollectionRegistryController()` to look up registered collections by slug.
+
+```typescript
+import { useCollectionRegistryController } from "@rebasepro/admin";
+```
+
+### CollectionRegistryController Interface
+
+```typescript
+type CollectionRegistryController<
+    DB = Record<string, unknown>,
+    EC extends EntityCollection = EntityCollection
+> = {
+    /** All registered collections */
+    collections?: EntityCollection[];
+
+    /** Whether the registry is ready */
+    initialised: boolean;
+
+    /** Get a collection by slug or path */
+    getCollection: <K extends keyof DB>(slugOrPath: Extract<K, string>, includeUserOverride?: boolean) => EC | undefined;
+
+    /** Get the raw (un-normalized) collection config — for the Visual Editor only */
+    getRawCollection: (slugOrPath: string) => EC | undefined;
+
+    /** Get all parent entity references for a path */
+    getParentReferencesFromPath: (path: string) => EntityReference[];
+
+    /** Get parent collection slugs for a path */
+    getParentCollectionSlugs: (path: string) => string[];
+
+    /** Get parent entity IDs for a path */
+    getParentEntityIds: (path: string) => string[];
+
+    /** Resolve IDs to paths */
+    convertIdsToPaths: (ids: string[]) => string[];
+};
+```
+
+### Example
+
+```tsx
+const registry = useCollectionRegistryController();
+
+// Check if a collection exists
+const products = registry.getCollection("products");
+if (products) {
+    console.log("Collection name:", products.name);
+    console.log("Properties:", Object.keys(products.properties));
+}
+
+// List all collections
+registry.collections?.forEach(c => {
+    console.log(c.slug, c.name);
+});
+```
+
+---
+
+## 4. Embedding Collections with CollectionPanel
+
+`CollectionPanel` is a high-level wrapper for embedding collection views inside custom pages (dashboards, home pages, entity detail views).
+
+```typescript
+import { CollectionPanel } from "@rebasepro/admin";
+```
+
+### CollectionPanelProps
+
+```typescript
+type CollectionPanelProps = {
+    /** Collection slug to display (e.g. "tasks") — required */
+    path: string;
+
+    /** Title above the collection. `false` to hide. Defaults to collection name. */
+    title?: string | false;
+
+    /** Force a view mode (table, card, etc.) */
+    viewMode?: ViewMode;
+
+    /** Override sort: [fieldName, direction] */
+    sort?: [string, "asc" | "desc"];
+
+    /** Max entities to display */
+    limit?: number;
+
+    /** Sync filter/sort with URL params (default: false) */
+    updateUrl?: boolean;
+
+    /** Entity open mode when clicking */
+    openEntityMode?: "side_panel" | "full_screen" | "split" | "dialog";
+
+    /** Container CSS class */
+    className?: string;
+
+    /** Additional collection-level overrides */
+    collectionOverrides?: Partial<EntityCollection>;
+};
+```
+
+### Examples
+
+```tsx
+// Simple embedded collection
+<CollectionPanel path="tasks" title="Pending Tasks" />
+
+// Table with sorting and limit
+<CollectionPanel
+    path="clients"
+    viewMode="table"
+    limit={10}
+    sort={["createdAt", "desc"]}
+/>
+
+// With a default filter
+<CollectionPanel
+    path="orders"
+    title={false}
+    openEntityMode="dialog"
+    collectionOverrides={{
+        defaultFilter: { status: ["!=", "completed"] }
+    }}
+/>
+```
+
+> **IMPORTANT FOR AGENTS:** `CollectionPanel` defaults `updateUrl` to `false` so embedded panels don't hijack the browser URL. Only set `updateUrl={true}` if you explicitly need URL sync.
+
+---
+
+## 5. Entity Selection Dialog
+
+Use `useEntitySelectionDialog()` to open a side dialog for selecting entities (same mechanism used by reference fields).
+
+```typescript
+import { useEntitySelectionDialog } from "@rebasepro/admin";
+```
+
+### Usage
+
+```tsx
+function MyComponent() {
+    const { open, close } = useEntitySelectionDialog<Product>({
+        path: "products",
+        onSingleEntitySelected: (entity) => {
+            console.log("Selected:", entity.id);
+            close();
+        }
+    });
+
+    return <Button onClick={open}>Select Product</Button>;
+}
+```
+
+The hook accepts all `EntitySelectionProps` except `path` (which you pass separately), plus an `onClose` callback.
+
+---
+
+## 6. Side Dialogs (Generic)
+
+Use `useSideDialogsController()` to open arbitrary side panels with custom React content. This is the lower-level mechanism behind entity side panels.
+
+```typescript
+import { useSideDialogsController } from "@rebasepro/admin";
+```
+
+### SideDialogsController Interface
+
+```typescript
+interface SideDialogsController {
+    /** Close the last panel */
+    close: () => void;
+
+    /** Currently open panels */
+    sidePanels: SideDialogPanelProps[];
+
+    /** Override all panels */
+    setSidePanels: (panels: SideDialogPanelProps[]) => void;
+
+    /** Open one or multiple side panels */
+    open: (panelProps: SideDialogPanelProps | SideDialogPanelProps[]) => void;
+
+    /** Replace the last panel */
+    replace: (panelProps: SideDialogPanelProps | SideDialogPanelProps[]) => void;
+}
+```
+
+### SideDialogPanelProps
+
+```typescript
+interface SideDialogPanelProps {
+    /** Unique key identifying this panel */
+    key: string;
+
+    /** React component to render inside the panel */
+    component: React.ReactNode;
+
+    /** Optional panel width (e.g. "90vw", "600px") */
+    width?: string;
+
+    /** When open, update the browser URL to this path */
+    urlPath?: string;
+
+    /** URL to navigate to when the panel is closed and there's no history */
+    parentUrlPath?: string;
+
+    /** Callback when the panel is closed */
+    onClose?: () => void;
+
+    /** Store additional data on the panel */
+    additional?: unknown;
+}
+```
+
+### Example
+
+```tsx
+const sideDialogs = useSideDialogsController();
+
+sideDialogs.open({
+    key: "my-custom-panel",
+    component: <MyCustomView data={someData} />,
+    width: "600px",
+    onClose: () => console.log("Panel closed")
+});
+```
+
+---
+
+## 7. Breadcrumbs
+
+Use `useBreadcrumbsController()` to read or set the breadcrumb trail.
+
+```typescript
+import { useBreadcrumbsController } from "@rebasepro/admin";
+```
+
+### BreadcrumbsController Interface
+
+```typescript
+interface BreadcrumbsController {
+    breadcrumbs: BreadcrumbEntry[];
+    set: (props: { breadcrumbs: BreadcrumbEntry[] }) => void;
+    updateCount: (id: string, count: number | null | undefined) => void;
+}
+
+interface BreadcrumbEntry {
+    title: string;
+    url: string;
+    count?: number | null;  // undefined = N/A, null = loading, number = loaded
+    id?: string;            // for targeted count updates
+}
+```
+
+### Example
+
+```tsx
+const breadcrumbs = useBreadcrumbsController();
+
+breadcrumbs.set({
+    breadcrumbs: [
+        { title: "Dashboard", url: "/" },
+        { title: "Products", url: "/c/products", id: "products", count: null },
+    ]
+});
+
+// Later, update the count without re-setting everything
+breadcrumbs.updateCount("products", 42);
+```
+
+---
+
+## 8. Navigation State
+
+Use `useNavigationStateController()` to access registered views, loading state, and trigger navigation refresh.
+
+```typescript
+import { useNavigationStateController } from "@rebasepro/admin";
+```
+
+### NavigationStateController Interface
+
+```typescript
+type NavigationStateController = {
+    /** Custom views added to the main navigation */
+    views?: AppView[];
+
+    /** Custom views added to admin navigation */
+    adminViews?: AppView[];
+
+    /** Top-level navigation entries and groups */
+    topLevelNavigation?: NavigationResult;
+
+    /** Whether navigation is still loading */
+    loading: boolean;
+
+    /** Error during navigation loading */
+    navigationLoadingError?: unknown;
+
+    /** Force a navigation recalculation */
+    refreshNavigation: () => void;
+
+    /** Registered plugins */
+    plugins?: RebasePlugin[];
+};
+```
+
+---
+
+## 9. CMS Context (All-in-One)
+
+Use `useCMSContext()` to get the full CMS context combining the core `RebaseContext` with all CMS-specific controllers.
+
+```typescript
+import { useCMSContext } from "@rebasepro/admin";
+```
+
+### CMSContext Type
+
+```typescript
+type CMSContext = RebaseContext & {
+    sideEntityController: SideEntityController;
+    sideDialogsController: SideDialogsController;
+    urlController: UrlController;
+    navigationStateController: NavigationStateController;
+    collectionRegistryController: CollectionRegistryController;
+};
+```
+
+### Example
+
+```tsx
+const context = useCMSContext();
+
+// Access any controller
+context.sideEntityController.open({ path: "products", entityId: "abc" });
+context.urlController.navigate(context.urlController.buildUrlCollectionPath("orders"));
+context.collectionRegistryController.getCollection("products");
+context.authController; // from RebaseContext
+context.data;           // DataSource from RebaseContext
+```
+
+> **TIP:** Use `useCMSContext()` instead of `useRebaseContext()` when you need CMS controllers (side panels, navigation, URL). Use `useRebaseContext()` from `@rebasepro/core` when you only need core context (auth, data, storage).
+
+---
+
+## 10. Common Patterns
+
+### Navigate to a collection and open an entity
+
+```tsx
+import { useUrlController, useSideEntityController } from "@rebasepro/admin";
+
+function navigateAndOpen() {
+    const urlController = useUrlController();
+    const sideEntityController = useSideEntityController();
+
+    // First navigate to the collection
+    urlController.navigate(urlController.buildUrlCollectionPath("products"));
+
+    // Then open the entity in the side drawer
+    sideEntityController.open({
+        path: "products",
+        entityId: "abc123"
+    });
+}
+```
+
+### Open entity from a custom view without navigating
+
+```tsx
+import { useSideEntityController } from "@rebasepro/admin";
+
+function MyCustomView() {
+    const sideEntityController = useSideEntityController();
+
+    return (
+        <button onClick={() => sideEntityController.open({
+            path: "products",
+            entityId: "abc123",
+            updateUrl: false  // don't change the URL
+        })}>
+            View Product
+        </button>
+    );
+}
+```
+
+### Programmatic entity creation from a custom view
+
+```tsx
+import { useSideEntityController } from "@rebasepro/admin";
+
+function CreateButton() {
+    const sideEntity = useSideEntityController();
+
+    return (
+        <button onClick={() => sideEntity.open({
+            path: "orders",
+            defaultValues: {
+                status: "pending",
+                createdAt: new Date()
+            },
+            closeOnSave: true,
+            onUpdate: ({ entity }) => {
+                console.log("Created order:", entity.id);
+            }
+        })}>
+            New Order
+        </button>
+    );
+}
+```
+
+---
+
+## Exported Components
+
+The admin package exports the following components (from `@rebasepro/admin`):
+
+| Component | Description |
+|-----------|-------------|
+| `RebaseCMS` | Declarative CMS config (collections, views, editor) — renders nothing |
+| `RebaseShell` | App shell (drawer, nav, routes, layout) — renders the actual UI |
+| `CollectionPanel` | Embed a collection view inside custom pages |
+| `EntityCollectionView` | The collection view component |
+| `EntityView` | Entity detail/edit view |
+| `EntityPreview` | Reference/relation preview chip |
+| `EntityCard` | Card representation of an entity |
+| `SideDialogs` | Side dialog container |
+| `SideEntityProvider` | Context provider for side entity controller |
+| `EntitySelectionTable` | Table for selecting entities |
+| `Scaffold` | Layout scaffold component |
+| `AppBar` | Top app bar |
+| `Drawer` / `DefaultDrawer` | Sidebar drawer |
+| `RebaseAuthGate` | Auth-gated wrapper |
+| `RebaseNavigation` | Navigation provider |
+| `RebaseLayout` | Layout wrapper |
+| `RebaseRouteDefs` | Route definitions |
+
+## Exported Hooks
+
+| Hook | Description |
+|------|-------------|
+| `useSideEntityController()` | Open/close entity side panels |
+| `useSideDialogsController()` | Open/close generic side dialogs |
+| `useUrlController()` | Build URLs and navigate |
+| `useNavigationStateController()` | Access navigation state |
+| `useCollectionRegistryController()` | Look up collections by slug |
+| `useBreadcrumbsController()` | Read/set breadcrumbs |
+| `useCMSContext()` | Full CMS context (core + CMS controllers) |
+| `useEntitySelectionDialog()` | Open entity selection dialog |
+| `useSelectionController()` | Multi-select controller |
+| `useEntityHistory()` | Entity version history |
+| `useApp()` | App-level utilities |
+
+## Exported Utilities
+
+| Utility | Description |
+|---------|-------------|
+| `addInitialSlash(path)` | Ensure path starts with `/` |
+| `removeInitialSlash(path)` | Strip leading `/` |
+| `removeTrailingSlash(path)` | Strip trailing `/` |
+| `removeInitialAndTrailingSlashes(path)` | Strip both |
+| `getLastSegment(path)` | Get last path segment |
+| `getCollectionBySlugWithin(collections, slug)` | Find collection in array |
+| `mergeEntityActions(...)` | Merge entity action arrays |
+| `resolveEntityAction(...)` | Resolve an entity action |
+| `resolveEntityView(...)` | Resolve an entity view |
+| `isReferenceProperty(prop)` | Check if property is a reference |
+| `isRelationProperty(prop)` | Check if property is a relation |
+| `getIconForProperty(prop)` | Get icon for a property type |
+
+## Built-in Entity Actions
+
+```typescript
+import {
+    editEntityAction,
+    copyEntityAction,
+    deleteEntityAction,
+    resetPasswordAction
+} from "@rebasepro/admin";
+```
+
+These are pre-built `EntityAction` objects that can be added to a collection's `entityActions` array.