@elevasis/sdk 1.5.3 → 1.5.4

package/reference/scaffold/ui/recipes.md

@@ -225,7 +225,7 @@ ui/src/features/reporting/
 
 ```ts
 import { useQuery } from '@tanstack/react-query'
-import { useApiClient } from '@/shared/api'
+import { useApiClient } from '@/lib/hooks/useApiClient'
 
 export function useReports() {
   const { apiRequest, isOrganizationReady } = useApiClient()
@@ -262,9 +262,9 @@ export function ReportingOverviewPage() {
 
 ### Explanation
 
-- **`@/*` alias:** resolves to `ui/src/*`. Use it for all cross-feature imports (e.g., `@/shared/api`, `@/features/auth`). Never use relative paths that cross feature boundaries.
+- **`@/*` alias:** resolves to `ui/src/*`. Use it for all cross-feature imports (e.g., `@/lib/hooks/useApiClient`, `@/features/auth`). Never use relative paths that cross feature boundaries.
 - **Server state in Query, client state in Zustand:** if data comes from an API, it belongs in a `useQuery` hook, not a Zustand slice. Zustand is for client-only UI state (open/close, selection, optimistic updates).
-- **`useApiClient`:** from `@/shared/api`. Returns `apiRequest` (an authenticated fetch wrapper) and `isOrganizationReady` (use this as `enabled` to avoid firing requests before the org is loaded).
+- **`useApiClient`:** from `@/lib/hooks/useApiClient`. Returns `apiRequest` (an authenticated fetch wrapper) and `isOrganizationReady` (use this as `enabled` to avoid firing requests before the org is loaded).
 - **`SubshellContentContainer` / `PageContainer`:** added in the route file, not in the feature component. Feature components should be layout-agnostic -- the route decides the shell treatment.
 - **No React, no Node imports in `foundations/`:** types shared between frontend and `operations/` live in `foundations/`. Feature components live only in `ui/src/features/`.
 
@@ -416,3 +416,118 @@ export const navItems: ExtendedLinksGroupProps[] = [
 - `./customization.md` -- customizing feature sidebars and pages via manifest composition
 - `ui/src/config/README.md` -- deeper guide for theme, background, and loader config files
 - `external/_template/.claude/rules/frontend.md` -- concise agent-oriented frontend conventions
+
+---
+
+## 6. Execute a Resource from a Surface
+
+Resources (workflows, agents, triggers) deploy to the Elevasis platform and can be triggered from any feature surface. This recipe shows how to declare the resource on a surface via the org model, share its input schema via `foundations/types/`, and render a button that executes it.
+
+### The Three Foundations Layers
+
+- **Org model** (`foundations/config/organization-model.ts`): semantic metadata -- which surfaces exist, what resources map to them, labels and colors.
+- **Entity contracts** (`foundations/types/entities.ts`): typed shapes for Project, Deal, etc. -- extend `BaseProject`, `BaseDeal` from `@elevasis/core/entities`.
+- **Resource I/O** (`foundations/types/index.ts`): Zod schemas for workflow inputs/outputs.
+
+### Code
+
+#### 1. Declare the resource on a surface
+
+`foundations/config/organization-model.ts`:
+
+```ts
+import { defineOrganizationModel, CRM_PIPELINE_SURFACE_ID } from '@elevasis/core/organization-model'
+
+export const organizationOverride = defineOrganizationModel({
+  branding: { /* ... */ },
+  resourceMappings: [
+    {
+      id: 'crm.pipeline.write-note',
+      surfaceId: CRM_PIPELINE_SURFACE_ID,
+      resourceId: 'my-project-write-note-workflow',
+      resourceType: 'workflow',
+      label: 'Write Note',
+      color: 'blue',
+      featureIds: ['crm'],
+      entityIds: ['crm.deal'],
+      capabilityIds: []
+    }
+  ]
+})
+```
+
+#### 2. Share the input schema
+
+`foundations/types/index.ts`:
+
+```ts
+import { z } from 'zod'
+
+export const writeNoteInputSchema = z.object({
+  dealId: z.string(),
+  note: z.string().min(1).max(2000)
+})
+
+export type WriteNoteInput = z.infer<typeof writeNoteInputSchema>
+```
+
+#### 3. Render the button
+
+`ui/src/features/crm/components/DealPanel.tsx`:
+
+```tsx
+import { RunResourceButton } from '@elevasis/ui/components'
+import { organizationModel } from '@foundation/config/organization-model'
+import { writeNoteInputSchema } from '@foundation/types'
+
+export function DealPanel({ dealId }: { dealId: string }) {
+  return (
+    <RunResourceButton
+      resourceId="my-project-write-note-workflow"
+      resourceType="workflow"
+      organizationModel={organizationModel}
+      getInput={() => ({
+        schema: writeNoteInputSchema,
+        defaults: { dealId }
+      })}
+      onSuccess={(result) => console.log('Started:', result.executionId)}
+    />
+  )
+}
+```
+
+The three `getInput` shapes:
+
+```tsx
+// Plain object (no form) -- executes immediately on click
+getInput={() => ({ dealId, note: 'Auto-generated' })}
+
+// Mixed (form for unfixed fields) -- modal opens with dealId pre-filled
+getInput={() => ({ schema: writeNoteInputSchema, defaults: { dealId } })}
+
+// Full form -- modal opens with all fields blank
+getInput={() => ({ schema: writeNoteInputSchema })}
+```
+
+#### 4. Optionally listen for live execution logs
+
+```tsx
+import { useExecutionLogSSE, useMergedExecution } from '@elevasis/ui/hooks'
+// Pass the SSE manager from your app's sse.ts wrapper and apiUrl from config.
+// For the full live-logs pattern see:
+// apps/command-center/src/features/operations/executions/
+```
+
+### How It Works
+
+- `RunResourceButton` inspects what `getInput()` returns: a plain object triggers execution immediately; `{ schema, defaults? }` opens a `ZodFormRenderer` modal so the user can fill in missing fields before submitting.
+- Label and color resolve in order: explicit props > `resourceMappings` entry matching `resourceId` > default `'Run'`. The `icon` prop is prop-only and is never inferred from the mapping.
+- `ZodFormRenderer` introspects the Zod schema at runtime and renders Mantine fields for each top-level key. Unsupported Zod types (nested objects, arrays, unions) fall back to a JSON textarea so the form always renders regardless of schema complexity.
+- Typed feature and surface constants (e.g. `CRM_PIPELINE_SURFACE_ID`) come from `@elevasis/core/organization-model`. See Issue 4 constants for the full list.
+- Entity contracts (Deal, Project) live in `foundations/types/entities.ts` and extend base types from `@elevasis/core/entities` -- see the entity recipe for the full shape.
+
+### Cross-References
+
+- `./feature-flags-and-gating.md` -- gating a surface or button by feature key or admin role
+- `@foundation/types/entities.ts` -- Deal, Project, and other entity contracts for this project
+- Recipe 5 (Add a Nav Item) -- how surfaces and nav entries are wired together