@proteos/component-sdk 0.41.1 → 0.42.0

package/src/hooks.ts

@@ -1,8 +1,11 @@
-import { useContext, useEffect, useState } from 'react'
+import { useCallback, useContext, useEffect, useMemo, useState } from 'react'
 
 import {
   type ComponentSdk,
   type NavigateOptions,
+  type OpenModalOptions,
+  type OverlayController,
+  postModalResult,
   RuntimeContext,
   type RuntimeContextValue,
 } from './context'
@@ -63,6 +66,80 @@ export function useApiBaseUrl(): string {
   return useRuntime().apiBaseUrl
 }
 
+const NOOP_OVERLAY: OverlayController = {
+  expand: () => {
+    console.warn(
+      '@proteos/component-sdk: useOverlayExpansion() has no effect — this runtime ' +
+        'does not support overlay promotion (older shell or non-promoting host).',
+    )
+  },
+  collapse: () => {},
+  isExpanded: () => false,
+}
+
+/**
+ * Manual overlay promotion — lifts the whole component iframe over the rest of
+ * the page so an overlay can escape the frame's box.
+ *
+ * You rarely need this. Every `@proteos/ui` overlay (Modal, Popover, Menu,
+ * Select, Tooltip, …) portals to the iframe document's `<body>`, which the
+ * runtime watches — those promote automatically, with no code. Reach for this
+ * hook only when you portal somewhere else yourself, or want the frame lifted
+ * *before* the overlay mounts. Reference-counted: pair every `expand()` with a
+ * `collapse()`.
+ */
+export function useOverlayExpansion(): OverlayController {
+  return useRuntime().overlay ?? NOOP_OVERLAY
+}
+
+/**
+ * Open ANOTHER component in a modal the host renders above everything — the
+ * cross-component flow (a picker, a wizard step, a confirm dialog shared by
+ * several components). Resolves with whatever that component closed with, or
+ * `undefined` if the user dismissed it.
+ *
+ * ```ts
+ * const openModal = useComponentModal()
+ * const picked = await openModal('contact-picker', { entity: 'contact' }, { title: 'Pick a contact' })
+ * ```
+ *
+ * For an overlay that is part of THIS component, just render a `<Modal>` from
+ * `@proteos/ui` — it promotes automatically.
+ */
+export function useComponentModal(): (
+  componentSlug: string,
+  props?: Record<string, unknown>,
+  options?: OpenModalOptions,
+) => Promise<unknown> {
+  return useRuntime().openModal
+}
+
+export interface ModalHost {
+  /** True when this component is rendered as the content of a host modal. */
+  isInModal: boolean
+  /** Close the host modal, resolving the opener's promise with `result`.
+   *  No-op outside a modal. */
+  close: (result?: unknown) => void
+}
+
+/**
+ * For a component that is being shown INSIDE a host modal (opened by another
+ * component's `useComponentModal()`): close it and hand a value back.
+ * `isInModal` is false on ordinary page-hosted mounts, so one component can
+ * serve both roles.
+ */
+export function useModalHost(): ModalHost {
+  const requestId = useRuntime().modalRequestId
+  const close = useCallback(
+    (result?: unknown) => {
+      if (requestId === undefined) return
+      postModalResult(requestId, result)
+    },
+    [requestId],
+  )
+  return useMemo(() => ({ isInModal: requestId !== undefined, close }), [requestId, close])
+}
+
 /**
  * A getter for the current bearer token. Returns a function (not the token)
  * because the token is refreshed in place — read it at call time for a raw

package/src/index.ts

@@ -7,15 +7,25 @@
 // Register the ambient `Window.__PROTEOS_RUNTIME__` augmentation.
 import './global'
 
-export type { ComponentSdk, NavigateOptions, RuntimeContextValue, RuntimeValue } from './context'
+export type {
+  ComponentSdk,
+  NavigateOptions,
+  OpenModalOptions,
+  OverlayController,
+  RuntimeContextValue,
+  RuntimeValue,
+} from './context'
 export { RuntimeProvider } from './context'
-export type { FillViewportOptions, HostLocation } from './hooks'
+export type { FillViewportOptions, HostLocation, ModalHost } from './hooks'
 export {
   useApiBaseUrl,
   useAuthToken,
+  useComponentModal,
   useFillViewportHeight,
   useHostLocation,
+  useModalHost,
   useNavigate,
+  useOverlayExpansion,
   usePageContext,
   useProps,
   useRuntime,
@@ -23,6 +33,7 @@ export {
 } from './hooks'
 export {
   type AuthRefreshMessage,
+  COMPONENT_OVERLAY_Z_INDEX,
   type DataInvalidateMessage,
   type Envelope,
   type ErrorMessage,
@@ -31,8 +42,14 @@ export {
   isHostMessage,
   isRuntimeMessage,
   MESSAGE_SOURCE,
+  type ModalClosedMessage,
+  type ModalResultMessage,
   type NavigateMessage,
+  type OpenModalMessage,
   type OpenPeekMessage,
+  type OverlayRect,
+  type OverlayRectMessage,
+  type OverlayStateMessage,
   type PageContext,
   type ReadyMessage,
   type ResizeMessage,

package/src/protocol.ts

@@ -10,6 +10,37 @@
 
 export const MESSAGE_SOURCE = 'proteos-component-runtime' as const
 
+/**
+ * z-index the component iframe is promoted to while one of its own overlays
+ * (modal, popover, menu, select, tooltip) is open. The iframe goes
+ * `position: fixed; inset: 0` at this z so the overlay — which portals to the
+ * IFRAME's body and would otherwise clip at the frame's box — can paint over
+ * the rest of the page.
+ *
+ * Host z ladder this slots into:
+ *   50    @proteos/ui Modal / Tooltip / ImageLightbox (default tier)
+ *   1000+ full-page panel stack (scrim 1000, panels 1001+n)
+ *   1090  peek scrim   1100  peek panel, ask-proteos window
+ *   1150  ← THIS
+ *   1200  menu popover, command palette, action dialog, component modal
+ *   1300  select popover
+ *
+ * Above the peek/full-page surfaces a component can live on, below the global
+ * host chrome. Note the cap: inside a peek (a `fixed` + z-index ancestor) the
+ * promoted iframe paints within that 1100 stacking context — it covers the
+ * peek's own content and everything under it, but host chrome at 1200+ still
+ * wins. That is the intended layering, not a bug.
+ */
+export const COMPONENT_OVERLAY_Z_INDEX = 1150
+
+/** Viewport-relative box of the iframe's in-flow placeholder, in CSS px. */
+export interface OverlayRect {
+  top: number
+  left: number
+  width: number
+  height: number
+}
+
 export interface PageContext {
   record?: Record<string, unknown>
   entity?: { slug: string; [key: string]: unknown }
@@ -39,6 +70,11 @@ export interface InitMessage {
   /** Org id for public mode — public endpoints carry the org in the path
    *  because there is no token to scope from. */
   orgId?: string
+  /** Set when this frame is the CONTENT of a host component modal (opened by
+   *  another component via OPEN_MODAL). The component reads it through
+   *  `useModalHost()` and closes with a result by posting MODAL_RESULT with
+   *  this id. Absent on ordinary page-hosted frames. */
+  modalRequestId?: string
 }
 
 export interface AuthRefreshMessage {
@@ -51,7 +87,30 @@ export interface DataInvalidateMessage {
   queryKey?: unknown[]
 }
 
-export type HostMessage = InitMessage | AuthRefreshMessage | DataInvalidateMessage
+/** Where the iframe's in-flow box sits in the host viewport. Sent while the
+ *  frame is promoted (OVERLAY_STATE open) so the runtime can keep its content
+ *  parked at the original rect while the iframe itself covers the viewport —
+ *  and re-sent when the host window resizes under an open overlay. */
+export interface OverlayRectMessage {
+  type: 'OVERLAY_RECT'
+  rect: OverlayRect
+}
+
+/** Resolution of an OPEN_MODAL request: the host modal closed. `result` is the
+ *  value the modal's component passed to MODAL_RESULT, and is absent when the
+ *  modal was dismissed (backdrop / Esc / ×). */
+export interface ModalClosedMessage {
+  type: 'MODAL_CLOSED'
+  requestId: string
+  result?: unknown
+}
+
+export type HostMessage =
+  | InitMessage
+  | AuthRefreshMessage
+  | DataInvalidateMessage
+  | OverlayRectMessage
+  | ModalClosedMessage
 
 // ── Runtime → host ──────────────────────────────────────────────────────────
 
@@ -77,6 +136,44 @@ export interface OpenPeekMessage {
   to: string
 }
 
+/** The runtime has (or no longer has) an overlay open and needs the host to
+ *  promote (or restore) the iframe. See {@link COMPONENT_OVERLAY_Z_INDEX}.
+ *
+ *  Same-origin today, so the runtime applies the promotion styles to its own
+ *  `window.frameElement` synchronously (pre-paint, no flicker) and this message
+ *  is the host's cue to MIRROR that state into React — gate RESIZE, hold the
+ *  placeholder height, start posting OVERLAY_RECT. When components move to a
+ *  dedicated origin the runtime can no longer touch the frame and this message
+ *  becomes the actuation instead; the runtime hides its overlay until the
+ *  answering OVERLAY_RECT arrives. */
+export interface OverlayStateMessage {
+  type: 'OVERLAY_STATE'
+  open: boolean
+}
+
+/** Ask the host to open ANOTHER component in a central modal, above everything
+ *  this frame could reach on its own. The host answers with MODAL_CLOSED
+ *  carrying the same `requestId`. */
+export interface OpenModalMessage {
+  type: 'OPEN_MODAL'
+  /** Correlates the eventual MODAL_CLOSED. Generated by the opener. */
+  requestId: string
+  /** Slug of the component to mount inside the modal. */
+  componentSlug: string
+  /** Props for that component (already literal values — no Liquid). */
+  props?: Record<string, unknown>
+  /** Optional modal heading. */
+  title?: string
+}
+
+/** Posted by the component INSIDE a host modal to close it with a value. The
+ *  `requestId` is the one INIT carried as `modalRequestId`. */
+export interface ModalResultMessage {
+  type: 'MODAL_RESULT'
+  requestId: string
+  result?: unknown
+}
+
 export interface ErrorMessage {
   type: 'ERROR'
   message: string
@@ -88,6 +185,9 @@ export type RuntimeMessage =
   | ResizeMessage
   | NavigateMessage
   | OpenPeekMessage
+  | OverlayStateMessage
+  | OpenModalMessage
+  | ModalResultMessage
   | ErrorMessage
 
 // Wire envelope: the message plus the source discriminator.

package/dist/chunk-DD7AKVFC.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/protocol.ts"],"names":[],"mappings":";AAUO,IAAM,cAAA,GAAiB;AAqFvB,SAAS,cAAc,IAAA,EAA8C;AAC1E,EAAA,OACE,OAAO,IAAA,KAAS,QAAA,IAChB,IAAA,KAAS,IAAA,IACR,KAA8B,MAAA,KAAW,cAAA,IAC1C,OAAQ,IAAA,CAA4B,IAAA,KAAS,QAAA;AAEjD;AAEO,SAAS,iBAAiB,IAAA,EAAiD;AAChF,EAAA,OACE,OAAO,IAAA,KAAS,QAAA,IAChB,IAAA,KAAS,IAAA,IACR,KAA8B,MAAA,KAAW,cAAA,IAC1C,OAAQ,IAAA,CAA4B,IAAA,KAAS,QAAA;AAEjD","file":"chunk-DD7AKVFC.js","sourcesContent":["// postMessage protocol between the host page and the component-runtime iframe.\n// This is the single source of truth for the wire contract: the host renderer\n// (clients/web .../component-frame.tsx), the runtime shell\n// (clients/web/component-runtime/shell.tsx), and the author-facing hooks\n// (this package's RuntimeProvider / useNavigate) all import these same types so\n// every end stays in lockstep.\n//\n// Every message carries `source: MESSAGE_SOURCE` so we can ignore the unrelated\n// postMessage traffic that shares the window (OIDC silent-renew, Vite HMR, …).\n\nexport const MESSAGE_SOURCE = 'proteos-component-runtime' as const\n\nexport interface PageContext {\n  record?: Record<string, unknown>\n  entity?: { slug: string; [key: string]: unknown }\n  params?: Record<string, unknown>\n  [key: string]: unknown\n}\n\n// ── Host → runtime ──────────────────────────────────────────────────────────\n\nexport interface InitMessage {\n  type: 'INIT'\n  /** Raw bearer token (the OIDC `id_token`). The runtime's ProteosClient\n   *  prepends `Bearer ` when building the Authorization header, so the host\n   *  sends the token verbatim — NOT a full `Bearer …` header value.\n   *  Empty string in public mode (`isPublic: true`). */\n  authToken: string\n  /** API origin the bundle endpoint + SDK calls resolve against. */\n  apiBaseUrl: string\n  /** Resolved props for the component (Liquid templating happens host-side). */\n  props: Record<string, unknown>\n  pageCtx: PageContext\n  /** PUBLIC mode: the component renders on an unauthenticated public page.\n   *  The shell fetches the bundle from the public endpoint (no bearer) and\n   *  injects a restricted sdk — only `functions.actions.invokePublic` reaches\n   *  the platform. Requires `orgId`. */\n  isPublic?: boolean\n  /** Org id for public mode — public endpoints carry the org in the path\n   *  because there is no token to scope from. */\n  orgId?: string\n}\n\nexport interface AuthRefreshMessage {\n  type: 'AUTH_REFRESH'\n  token: string\n}\n\nexport interface DataInvalidateMessage {\n  type: 'DATA_INVALIDATE'\n  queryKey?: unknown[]\n}\n\nexport type HostMessage = InitMessage | AuthRefreshMessage | DataInvalidateMessage\n\n// ── Runtime → host ──────────────────────────────────────────────────────────\n\nexport interface ReadyMessage {\n  type: 'READY'\n}\n\nexport interface ResizeMessage {\n  type: 'RESIZE'\n  height: number\n}\n\nexport interface NavigateMessage {\n  type: 'NAVIGATE'\n  to: string\n}\n\n/** Open an in-app path in a peek (slide-over) panel instead of full-page\n *  navigation. Same `/…` in-app path grammar as NAVIGATE; the host decides\n *  what can peek (today: platform pages) and falls back to NAVIGATE otherwise. */\nexport interface OpenPeekMessage {\n  type: 'OPEN_PEEK'\n  to: string\n}\n\nexport interface ErrorMessage {\n  type: 'ERROR'\n  message: string\n  stack?: string\n}\n\nexport type RuntimeMessage =\n  | ReadyMessage\n  | ResizeMessage\n  | NavigateMessage\n  | OpenPeekMessage\n  | ErrorMessage\n\n// Wire envelope: the message plus the source discriminator.\nexport type Envelope<T> = T & { source: typeof MESSAGE_SOURCE }\n\nexport function isHostMessage(data: unknown): data is Envelope<HostMessage> {\n  return (\n    typeof data === 'object' &&\n    data !== null &&\n    (data as { source?: unknown }).source === MESSAGE_SOURCE &&\n    typeof (data as { type?: unknown }).type === 'string'\n  )\n}\n\nexport function isRuntimeMessage(data: unknown): data is Envelope<RuntimeMessage> {\n  return (\n    typeof data === 'object' &&\n    data !== null &&\n    (data as { source?: unknown }).source === MESSAGE_SOURCE &&\n    typeof (data as { type?: unknown }).type === 'string'\n  )\n}\n"]}

package/dist/chunk-GL7ZEEP4.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/protocol.ts"],"names":[],"mappings":";;;AAUO,IAAM,cAAA,GAAiB;AAqFvB,SAAS,cAAc,IAAA,EAA8C;AAC1E,EAAA,OACE,OAAO,IAAA,KAAS,QAAA,IAChB,IAAA,KAAS,IAAA,IACR,KAA8B,MAAA,KAAW,cAAA,IAC1C,OAAQ,IAAA,CAA4B,IAAA,KAAS,QAAA;AAEjD;AAEO,SAAS,iBAAiB,IAAA,EAAiD;AAChF,EAAA,OACE,OAAO,IAAA,KAAS,QAAA,IAChB,IAAA,KAAS,IAAA,IACR,KAA8B,MAAA,KAAW,cAAA,IAC1C,OAAQ,IAAA,CAA4B,IAAA,KAAS,QAAA;AAEjD","file":"chunk-GL7ZEEP4.cjs","sourcesContent":["// postMessage protocol between the host page and the component-runtime iframe.\n// This is the single source of truth for the wire contract: the host renderer\n// (clients/web .../component-frame.tsx), the runtime shell\n// (clients/web/component-runtime/shell.tsx), and the author-facing hooks\n// (this package's RuntimeProvider / useNavigate) all import these same types so\n// every end stays in lockstep.\n//\n// Every message carries `source: MESSAGE_SOURCE` so we can ignore the unrelated\n// postMessage traffic that shares the window (OIDC silent-renew, Vite HMR, …).\n\nexport const MESSAGE_SOURCE = 'proteos-component-runtime' as const\n\nexport interface PageContext {\n  record?: Record<string, unknown>\n  entity?: { slug: string; [key: string]: unknown }\n  params?: Record<string, unknown>\n  [key: string]: unknown\n}\n\n// ── Host → runtime ──────────────────────────────────────────────────────────\n\nexport interface InitMessage {\n  type: 'INIT'\n  /** Raw bearer token (the OIDC `id_token`). The runtime's ProteosClient\n   *  prepends `Bearer ` when building the Authorization header, so the host\n   *  sends the token verbatim — NOT a full `Bearer …` header value.\n   *  Empty string in public mode (`isPublic: true`). */\n  authToken: string\n  /** API origin the bundle endpoint + SDK calls resolve against. */\n  apiBaseUrl: string\n  /** Resolved props for the component (Liquid templating happens host-side). */\n  props: Record<string, unknown>\n  pageCtx: PageContext\n  /** PUBLIC mode: the component renders on an unauthenticated public page.\n   *  The shell fetches the bundle from the public endpoint (no bearer) and\n   *  injects a restricted sdk — only `functions.actions.invokePublic` reaches\n   *  the platform. Requires `orgId`. */\n  isPublic?: boolean\n  /** Org id for public mode — public endpoints carry the org in the path\n   *  because there is no token to scope from. */\n  orgId?: string\n}\n\nexport interface AuthRefreshMessage {\n  type: 'AUTH_REFRESH'\n  token: string\n}\n\nexport interface DataInvalidateMessage {\n  type: 'DATA_INVALIDATE'\n  queryKey?: unknown[]\n}\n\nexport type HostMessage = InitMessage | AuthRefreshMessage | DataInvalidateMessage\n\n// ── Runtime → host ──────────────────────────────────────────────────────────\n\nexport interface ReadyMessage {\n  type: 'READY'\n}\n\nexport interface ResizeMessage {\n  type: 'RESIZE'\n  height: number\n}\n\nexport interface NavigateMessage {\n  type: 'NAVIGATE'\n  to: string\n}\n\n/** Open an in-app path in a peek (slide-over) panel instead of full-page\n *  navigation. Same `/…` in-app path grammar as NAVIGATE; the host decides\n *  what can peek (today: platform pages) and falls back to NAVIGATE otherwise. */\nexport interface OpenPeekMessage {\n  type: 'OPEN_PEEK'\n  to: string\n}\n\nexport interface ErrorMessage {\n  type: 'ERROR'\n  message: string\n  stack?: string\n}\n\nexport type RuntimeMessage =\n  | ReadyMessage\n  | ResizeMessage\n  | NavigateMessage\n  | OpenPeekMessage\n  | ErrorMessage\n\n// Wire envelope: the message plus the source discriminator.\nexport type Envelope<T> = T & { source: typeof MESSAGE_SOURCE }\n\nexport function isHostMessage(data: unknown): data is Envelope<HostMessage> {\n  return (\n    typeof data === 'object' &&\n    data !== null &&\n    (data as { source?: unknown }).source === MESSAGE_SOURCE &&\n    typeof (data as { type?: unknown }).type === 'string'\n  )\n}\n\nexport function isRuntimeMessage(data: unknown): data is Envelope<RuntimeMessage> {\n  return (\n    typeof data === 'object' &&\n    data !== null &&\n    (data as { source?: unknown }).source === MESSAGE_SOURCE &&\n    typeof (data as { type?: unknown }).type === 'string'\n  )\n}\n"]}