@gravitee/graphene-policy-studio 1.0.0-alpha.1 → 1.0.0-alpha.2

package/USAGE_GUIDE.md

@@ -0,0 +1,211 @@
+# Using Policy Studio
+
+> **Scope:** These rules only apply when working with `@gravitee/graphene-policy-studio`. Do not apply them to unrelated parts of the codebase.
+
+Policy Studio is the Graphene module for editing API flows, plans, and policy steps. The host application owns API data and persistence; the library provides the React contract (`PolicyStudioProvider`), domain types, and (as components land) studio UI.
+
+Browse the live component catalog in this package’s Storybook (local: `yarn workspace @gravitee/graphene-policy-studio storybook`).
+
+## Package exports
+
+| Export | What it is |
+| ------ | ---------- |
+| `@gravitee/graphene-policy-studio` | Single entry: provider, context hook, domain types, phase mappings, and `PolicyStudioLayout` (POC shell). |
+
+**Named exports (main integration surface):**
+
+| Symbol | Role |
+| ------ | ---- |
+| `PolicyStudioProvider` | Host contract wrapper — required at the root of any studio tree |
+| `usePolicyStudioContext` | Read studio data and cached fetchers from child components |
+| `PolicyStudioProviderProps`, `PolicyStudioContextValue` | TypeScript types for props and context |
+| `PolicyStudioLayout` | Layout shell (sidebar + info bar + canvas regions) — POC, may evolve |
+| `getFlowPhases`, `getProtocolType` | Map `ApiType` → flow phases and protocol |
+| `API_TYPE_TO_PROTOCOL`, `FLOW_PHASES_BY_API_TYPE` | Static lookup tables |
+| Domain types | `ApiType`, `Policy`, `Plan`, `Flow`, `SaveOutput`, `PolicyDocumentation`, etc. |
+
+There are no subpath exports (e.g. no `@gravitee/graphene-policy-studio/context`). Import everything from the package root.
+
+## Dependencies (what the host needs)
+
+| Dependency | Required | Notes |
+| ---------- | -------- | ----- |
+| `react`, `react-dom` | Yes (^19) | Provider and future UI components |
+| `@gravitee/graphene-core` | Yes (^2) | Shared primitives used by studio UI (`cn`, `ScrollArea`, …) |
+| `tailwindcss` | Optional (^4) | Recommended when using layout/components that rely on Graphene utility classes |
+
+Install:
+
+```bash
+yarn add @gravitee/graphene-policy-studio @gravitee/graphene-core react react-dom
+```
+
+The host should also follow [Graphene integration](../core/USAGE_GUIDE.md) (fonts, styles, and optionally Tailwind theme) so studio UI matches the design system.
+
+## Imports
+
+```tsx
+import {
+  PolicyStudioProvider,
+  usePolicyStudioContext,
+  getFlowPhases,
+  type ApiType,
+  type Policy,
+  type SaveOutput,
+} from '@gravitee/graphene-policy-studio';
+```
+
+Never import from internal paths under the package source tree. Only the published entry is supported.
+
+## Host integration (`PolicyStudioProvider`)
+
+Wrap your API policy editing page with `PolicyStudioProvider`. The host supplies domain data and three callbacks: save, schema fetch, and documentation fetch.
+
+### Required props
+
+| Prop | Type | Role |
+| ---- | ---- | ---- |
+| `apiType` | `ApiType` | Drives flow phases and protocol (`PROXY`, `MESSAGE`, `MCP_PROXY`, …) |
+| `policies` | `readonly Policy[]` | Policy catalog for the API |
+| `sharedPolicyGroups` | `readonly SharedPolicyGroupPolicy[]` | Shared policy groups available to the API |
+| `plans` | `readonly Plan[]` | Plans and their flows |
+| `commonFlows` | `readonly Flow[]` | API-level flows |
+| `entrypointsInfo` | `readonly ConnectorInfo[]` | Entrypoint connectors (used for connector filtering) |
+| `endpointsInfo` | `readonly ConnectorInfo[]` | Endpoint connectors |
+| `flowExecution` | `FlowExecution` | Flow matching mode and `matchRequired` |
+| `onSave` | `(output: SaveOutput) => void` | Persist studio changes (delta only) |
+| `onFetchPolicySchema` | `(policy: Policy) => Promise<unknown>` | Host API: JSON schema for policy config |
+| `onFetchPolicyDocumentation` | `(policy: Policy) => Promise<string \| PolicyDocumentation>` | Host API: policy docs |
+| `children` | `React.ReactNode` | Studio UI or custom consumers |
+
+### Optional props
+
+| Prop | Default | Role |
+| ---- | ------- | ---- |
+| `readOnly` | `false` | Disable editing in the studio |
+| `loading` | `false` | Show loading state in studio consumers |
+
+### Performance
+
+- **Memoize** array props (`policies`, `plans`, `commonFlows`, …) and `onSave` with `useMemo` / `useCallback`. They are in the context `useMemo` dependency array; new references every render force all consumers to re-render.
+- **Fetcher callbacks** (`onFetchPolicySchema`, `onFetchPolicyDocumentation`) are captured on **first mount** inside the provider. Keep them referentially stable for the lifetime of the provider, or ensure they close over values that do not change.
+
+### To implement
+
+Copy the snippet from `snippets/policy-studio-provider-host.tsx` and replace the placeholder comments with your API data and handlers. See Storybook **Policy Studio/PolicyStudioProvider** for interactive cache and save behavior.
+
+```mermaid
+flowchart TB
+  Host[Host app]
+  Provider[PolicyStudioProvider]
+  Children[Studio UI or usePolicyStudioContext]
+  Host -->|policies plans onSave fetchers| Provider
+  Provider --> Children
+```
+
+## Context API (`usePolicyStudioContext`)
+
+Call from any descendant of `PolicyStudioProvider`:
+
+```tsx
+function PolicyConfigPanel() {
+  const { fetchPolicySchema, policies, readOnly, onSave } = usePolicyStudioContext();
+  // ...
+}
+```
+
+**Exposed on context:**
+
+- All data props from the provider (`apiType`, `policies`, `plans`, `commonFlows`, …)
+- `readOnly`, `loading`
+- `onSave` — same callback the host passed in
+- `fetchPolicySchema` — cached wrapper (not the raw host callback)
+- `fetchPolicyDocumentation` — cached, normalized wrapper
+
+Throws if used outside `PolicyStudioProvider`.
+
+## Fetcher contract
+
+### Policy schema (`onFetchPolicySchema` → `fetchPolicySchema`)
+
+- Host returns `Promise<unknown>` (typically a JSON Schema object).
+- Cached **per `policy.id`** for the lifetime of the provider mount.
+- **Concurrent** calls for the same id share one in-flight promise.
+- **Rejected** promises are **evicted** from the cache; the next call retries the host fetcher (transient network errors are not permanently cached).
+
+Use `fetchPolicySchema` from context in UI — do not call the host callback directly from children.
+
+### Policy documentation (`onFetchPolicyDocumentation` → `fetchPolicyDocumentation`)
+
+- Host may return a raw `string` (treated as ASCIIDOC: `{ content, language: 'ASCIIDOC' }`) or a `PolicyDocumentation` object.
+- Empty content and fetch **errors** resolve to a standard placeholder: `{ content: 'No documentation available.', language: 'MARKDOWN' }`.
+- Cached per `policy.id` like schema; concurrent deduplication applies.
+
+Use `fetchPolicyDocumentation` from context — it always returns `Promise<PolicyDocumentation>`.
+
+## Save contract
+
+`onSave` receives a **`SaveOutput` delta**, not the full API entity:
+
+```ts
+type SaveOutput = {
+  readonly commonFlows?: readonly Flow[];
+  readonly flowExecution?: FlowExecution;
+  readonly plansToUpdate?: readonly Plan[];
+};
+```
+
+The host merges this delta into its API model and persists. Saving does not clear schema or documentation caches.
+
+## Domain helpers
+
+Align host payloads with studio rules:
+
+```tsx
+import { getFlowPhases, getProtocolType, API_TYPE_TO_PROTOCOL } from '@gravitee/graphene-policy-studio';
+
+const phases = getFlowPhases('PROXY'); // ['REQUEST', 'RESPONSE']
+const protocol = getProtocolType('MESSAGE'); // 'HTTP_MESSAGE'
+```
+
+| Helper | Use |
+| ------ | --- |
+| `getFlowPhases(apiType)` | Which phases to show in the canvas for this API type |
+| `getProtocolType(apiType)` | Protocol key used for policy compatibility |
+| `FLOW_PHASES_BY_API_TYPE` | Static phase list per API type |
+| `API_TYPE_TO_PROTOCOL` | Static protocol mapping |
+
+## Key types
+
+| Type | Purpose |
+| ---- | ------- |
+| `ApiType` | `PROXY`, `MESSAGE`, `MCP_PROXY`, `LLM_PROXY`, `NATIVE`, `A2A_PROXY` |
+| `Policy` | Catalog entry (`id`, `name`, optional `category`, `icon`, …) |
+| `Flow` | Selectors + phase steps (`request`, `response`, `connect`, …) |
+| `Plan` | `id`, `name`, `flows` |
+| `Step` | Policy step on a flow (`policy`, `configuration`, `enabled`, …) |
+| `SaveOutput` | Delta passed to `onSave` |
+| `PolicyDocumentation` | `{ content: string; language: 'MARKDOWN' \| 'ASCIIDOC' }` |
+
+Import the named types from `@gravitee/graphene-policy-studio` for full TypeScript shapes in your host app.
+
+## Layout shell (`PolicyStudioLayout`)
+
+Optional POC layout: three regions (sidebar, info bar, main). Requires Graphene styles/Tailwind in the host. Most POC components are not exported yet — build custom UI with `usePolicyStudioContext()` or follow in-repo Storybook under **Policy Studio - POC** until production `components/` ship.
+
+## Common mistakes to avoid
+
+- Passing **inline arrays** (`policies={[...]}`) or **inline callbacks** without `useMemo` / `useCallback` — causes unnecessary context updates.
+- Recreating **fetcher functions** on every render while expecting updated closures — fetchers are frozen at first mount.
+- Calling **`onFetchPolicySchema`** from children instead of **`fetchPolicySchema`** from context — bypasses cache and deduplication.
+- Treating documentation fetch results as always `string` — use context’s normalized `PolicyDocumentation`.
+- Expecting **`onSave`** to receive the full API definition — only `SaveOutput` fields the user changed.
+- Using Policy Studio **without** `@gravitee/graphene-core` styling when rendering exported layout/components — UI will look unstyled.
+
+## Snippets
+
+| File | When to use |
+| ---- | ----------- |
+| `snippets/policy-studio-provider-host.tsx` | First integration: provider + memoized host callbacks |
+
+Snippets ship in the npm package under `node_modules/@gravitee/graphene-policy-studio/snippets/`. They are copy-paste templates, not importable modules.

package/dist/context/PolicyStudioProvider.d.ts

@@ -0,0 +1,46 @@
+import { ApiType, ConnectorInfo, Flow, FlowExecution, Plan, Policy, PolicyDocumentation, SaveOutput, SharedPolicyGroupPolicy } from '../types';
+/**
+ * Props for the Policy Studio host contract.
+ *
+ * Array and callback props (`policies`, `plans`, `onSave`, `onFetchPolicySchema`, etc.)
+ * are included in the context `useMemo` dependency array. Hosts should memoize these
+ * values (e.g. via `useMemo` / `useCallback`) to avoid unnecessary context re-renders.
+ *
+ * Fetcher callbacks (`onFetchPolicySchema`, `onFetchPolicyDocumentation`) are captured
+ * by `useRef` on first mount — their identity is frozen for the lifetime of the provider.
+ * Ensure they are referentially stable or close over values that won't change.
+ */
+export interface PolicyStudioProviderProps {
+    readonly apiType: ApiType;
+    readonly policies: readonly Policy[];
+    readonly sharedPolicyGroups: readonly SharedPolicyGroupPolicy[];
+    readonly plans: readonly Plan[];
+    readonly commonFlows: readonly Flow[];
+    readonly entrypointsInfo: readonly ConnectorInfo[];
+    readonly endpointsInfo: readonly ConnectorInfo[];
+    readonly flowExecution: FlowExecution;
+    readonly readOnly?: boolean;
+    readonly loading?: boolean;
+    readonly onSave: (output: SaveOutput) => void;
+    readonly onFetchPolicySchema: (policy: Policy) => Promise<unknown>;
+    readonly onFetchPolicyDocumentation: (policy: Policy) => Promise<string | PolicyDocumentation>;
+    readonly children: React.ReactNode;
+}
+export interface PolicyStudioContextValue {
+    readonly apiType: ApiType;
+    readonly policies: readonly Policy[];
+    readonly sharedPolicyGroups: readonly SharedPolicyGroupPolicy[];
+    readonly plans: readonly Plan[];
+    readonly commonFlows: readonly Flow[];
+    readonly entrypointsInfo: readonly ConnectorInfo[];
+    readonly endpointsInfo: readonly ConnectorInfo[];
+    readonly flowExecution: FlowExecution;
+    readonly readOnly: boolean;
+    readonly loading: boolean;
+    readonly onSave: (output: SaveOutput) => void;
+    readonly fetchPolicySchema: (policy: Policy) => Promise<unknown>;
+    readonly fetchPolicyDocumentation: (policy: Policy) => Promise<PolicyDocumentation>;
+}
+export declare function PolicyStudioProvider({ apiType, policies, sharedPolicyGroups, plans, commonFlows, entrypointsInfo, endpointsInfo, flowExecution, readOnly, loading, onSave, onFetchPolicySchema, onFetchPolicyDocumentation, children, }: PolicyStudioProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function usePolicyStudioContext(): PolicyStudioContextValue;
+//# sourceMappingURL=PolicyStudioProvider.d.ts.map

package/dist/context/PolicyStudioProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PolicyStudioProvider.d.ts","sourceRoot":"","sources":["../../src/context/PolicyStudioProvider.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,OAAO,EACP,aAAa,EACb,IAAI,EACJ,aAAa,EACb,IAAI,EACJ,MAAM,EACN,mBAAmB,EACnB,UAAU,EACV,uBAAuB,EACxB,MAAM,UAAU,CAAC;AAIlB;;;;;;;;;;GAUG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAChE,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,SAAS,IAAI,EAAE,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,SAAS,aAAa,EAAE,CAAC;IACjD,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IAC9C,QAAQ,CAAC,mBAAmB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,QAAQ,CAAC,0BAA0B,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,mBAAmB,CAAC,CAAC;IAC/F,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,uBAAuB,EAAE,CAAC;IAChE,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,SAAS,IAAI,EAAE,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,SAAS,aAAa,EAAE,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,SAAS,aAAa,EAAE,CAAC;IACjD,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IAC9C,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,QAAQ,CAAC,wBAAwB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACrF;AAQD,wBAAgB,oBAAoB,CAAC,EACnC,OAAO,EACP,QAAQ,EACR,kBAAkB,EAClB,KAAK,EACL,WAAW,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,QAAgB,EAChB,OAAe,EACf,MAAM,EACN,mBAAmB,EACnB,0BAA0B,EAC1B,QAAQ,GACT,EAAE,yBAAyB,2CAwC3B;AAID,wBAAgB,sBAAsB,IAAI,wBAAwB,CAMjE"}

package/dist/context/index.d.ts

@@ -0,0 +1,3 @@
+export { PolicyStudioProvider, usePolicyStudioContext } from './PolicyStudioProvider';
+export type { PolicyStudioContextValue, PolicyStudioProviderProps } from './PolicyStudioProvider';
+//# sourceMappingURL=index.d.ts.map

package/dist/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACtF,YAAY,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/hooks/use-policy-docs.d.ts

@@ -0,0 +1,19 @@
+import { Policy, PolicyDocumentation } from '../types';
+interface UsePolicyDocsOptions {
+    readonly onFetchPolicySchema: (policy: Policy) => Promise<unknown>;
+    readonly onFetchPolicyDocumentation: (policy: Policy) => Promise<string | PolicyDocumentation>;
+}
+interface UsePolicyDocsResult {
+    readonly fetchPolicySchema: (policy: Policy) => Promise<unknown>;
+    readonly fetchPolicyDocumentation: (policy: Policy) => Promise<PolicyDocumentation>;
+}
+/**
+ * Composes host-provided fetchers with per-instance caching (spec 15).
+ *
+ * Cache maps are stored in refs so they persist across re-renders but are
+ * scoped to a single provider mount — matching the "per-service-instance"
+ * requirement from the spec.
+ */
+export declare function usePolicyDocs({ onFetchPolicySchema, onFetchPolicyDocumentation, }: UsePolicyDocsOptions): UsePolicyDocsResult;
+export {};
+//# sourceMappingURL=use-policy-docs.d.ts.map

package/dist/hooks/use-policy-docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-policy-docs.d.ts","sourceRoot":"","sources":["../../src/hooks/use-policy-docs.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE5D,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,mBAAmB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACnE,QAAQ,CAAC,0BAA0B,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,mBAAmB,CAAC,CAAC;CAChG;AAED,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,QAAQ,CAAC,wBAAwB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACrF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,EAC5B,mBAAmB,EACnB,0BAA0B,GAC3B,EAAE,oBAAoB,GAAG,mBAAmB,CAS5C"}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from './context';
 export * from './poc/index';
 export * from './mappings';
 export * from './types';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -1,23 +1,118 @@
-import { ScrollArea as e, cn as t } from "@gravitee/graphene-core";
-import { jsx as n, jsxs as r } from "react/jsx-runtime";
+import { createContext as e, useCallback as t, useContext as n, useMemo as r, useRef as i } from "react";
+import { jsx as a, jsxs as o } from "react/jsx-runtime";
+import { ScrollArea as s, cn as c } from "@gravitee/graphene-core";
+//#region src/lib/policy-documentation.ts
+var l = {
+	content: "No documentation available.",
+	language: "MARKDOWN"
+};
+function u(e) {
+	return typeof e == "object" && !!e && "content" in e && typeof e.content == "string" && "language" in e;
+}
+function d(e) {
+	return u(e) ? e.content ? e : l : e ? {
+		content: e,
+		language: "ASCIIDOC"
+	} : l;
+}
+function f(e) {
+	return async (t) => {
+		try {
+			return d(await e(t));
+		} catch {
+			return l;
+		}
+	};
+}
+//#endregion
+//#region src/lib/policy-fetch-cache.ts
+function p(e) {
+	let t = /* @__PURE__ */ new Map();
+	function n(n) {
+		let r = t.get(n.id);
+		if (r) return r;
+		let i = e(n);
+		return t.set(n.id, i), i.catch(() => t.delete(n.id)), i;
+	}
+	return {
+		fetch: n,
+		cache: t
+	};
+}
+//#endregion
+//#region src/hooks/use-policy-docs.ts
+function m({ onFetchPolicySchema: e, onFetchPolicyDocumentation: n }) {
+	let r = i(p(e)), a = i(p(f(n)));
+	return {
+		fetchPolicySchema: t((e) => r.current.fetch(e), []),
+		fetchPolicyDocumentation: t((e) => a.current.fetch(e), [])
+	};
+}
+//#endregion
+//#region src/context/PolicyStudioProvider.tsx
+var h = e(null);
+function g({ apiType: e, policies: t, sharedPolicyGroups: n, plans: i, commonFlows: o, entrypointsInfo: s, endpointsInfo: c, flowExecution: l, readOnly: u = !1, loading: d = !1, onSave: f, onFetchPolicySchema: p, onFetchPolicyDocumentation: g, children: _ }) {
+	let { fetchPolicySchema: v, fetchPolicyDocumentation: y } = m({
+		onFetchPolicySchema: p,
+		onFetchPolicyDocumentation: g
+	}), b = r(() => ({
+		apiType: e,
+		policies: t,
+		sharedPolicyGroups: n,
+		plans: i,
+		commonFlows: o,
+		entrypointsInfo: s,
+		endpointsInfo: c,
+		flowExecution: l,
+		readOnly: u,
+		loading: d,
+		onSave: f,
+		fetchPolicySchema: v,
+		fetchPolicyDocumentation: y
+	}), [
+		e,
+		t,
+		n,
+		i,
+		o,
+		s,
+		c,
+		l,
+		u,
+		d,
+		f,
+		v,
+		y
+	]);
+	return /* @__PURE__ */ a(h.Provider, {
+		value: b,
+		children: _
+	});
+}
+function _() {
+	let e = n(h);
+	if (!e) throw Error("usePolicyStudioContext must be used within a PolicyStudioProvider.");
+	return e;
+}
+//#endregion
 //#region src/poc/PolicyStudioLayout.tsx
-function i({ sidebar: i, infoBar: a, children: o, className: s }) {
-	return /* @__PURE__ */ r("div", {
-		className: t("grid h-full grid-cols-[240px_1fr] grid-rows-[auto_1fr] overflow-hidden", s),
+function v({ sidebar: e, infoBar: t, children: n, className: r }) {
+	return /* @__PURE__ */ o("div", {
+		className: c("grid h-full grid-cols-[240px_1fr] grid-rows-[auto_1fr] overflow-hidden", r),
 		children: [
-			/* @__PURE__ */ n(e, {
+			/* @__PURE__ */ a(s, {
 				className: "row-span-2 border-r bg-background",
-				children: i
+				children: e
 			}),
-			/* @__PURE__ */ n("div", {
+			/* @__PURE__ */ a("div", {
 				className: "min-w-0",
-				children: a
+				children: t
 			}),
-			/* @__PURE__ */ n(e, {
+			/* @__PURE__ */ a(s, {
 				className: "min-w-0 bg-background",
-				children: /* @__PURE__ */ n("div", {
+				children: /* @__PURE__ */ a("div", {
 					className: "p-6",
-					children: o
+					children: n
 				})
 			})
 		]
@@ -25,14 +120,14 @@ function i({ sidebar: i, infoBar: a, children: o, className: s }) {
 }
 //#endregion
 //#region src/mappings.ts
-var a = {
+var y = {
 	A2A_PROXY: "A2A_PROXY",
 	LLM_PROXY: "LLM_PROXY",
 	MCP_PROXY: "MCP_PROXY",
 	MESSAGE: "HTTP_MESSAGE",
 	NATIVE: "NATIVE_KAFKA",
 	PROXY: "HTTP_PROXY"
-}, o = {
+}, b = {
 	A2A_PROXY: [],
 	LLM_PROXY: ["REQUEST", "RESPONSE"],
 	MCP_PROXY: ["REQUEST", "RESPONSE"],
@@ -50,11 +145,11 @@ var a = {
 	],
 	PROXY: ["REQUEST", "RESPONSE"]
 };
-function s(e) {
-	return a[e];
+function x(e) {
+	return y[e];
 }
-function c(e) {
-	return o[e];
+function S(e) {
+	return b[e];
 }
 //#endregion
-export { a as API_TYPE_TO_PROTOCOL, o as FLOW_PHASES_BY_API_TYPE, i as PolicyStudioLayout, c as getFlowPhases, s as getProtocolType };
+export { y as API_TYPE_TO_PROTOCOL, b as FLOW_PHASES_BY_API_TYPE, v as PolicyStudioLayout, g as PolicyStudioProvider, S as getFlowPhases, x as getProtocolType, _ as usePolicyStudioContext };

package/dist/lib/policy-documentation.d.ts

@@ -0,0 +1,16 @@
+import { Policy, PolicyDocumentation } from '../types';
+/**
+ * Normalize a raw fetcher result into a `PolicyDocumentation`.
+ *
+ * - Raw `string` → `{ content, language: 'ASCIIDOC' }` (spec 15 string fallback).
+ * - Empty content or `null`/`undefined` → standard placeholder.
+ * - Already `PolicyDocumentation` → pass through.
+ */
+export declare function normalizePolicyDocumentation(raw: string | PolicyDocumentation): PolicyDocumentation;
+/**
+ * Wraps a host-provided documentation fetcher so callers always receive
+ * a `PolicyDocumentation` — errors and empty results resolve to the
+ * standard fallback instead of rejecting.
+ */
+export declare function createNormalizedDocumentationFetcher(rawFetcher: (policy: Policy) => Promise<string | PolicyDocumentation>): (policy: Policy) => Promise<PolicyDocumentation>;
+//# sourceMappingURL=policy-documentation.d.ts.map

package/dist/lib/policy-documentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-documentation.d.ts","sourceRoot":"","sources":["../../src/lib/policy-documentation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAiB5D;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,GAAG,mBAAmB,CAKnG;AAED;;;;GAIG;AACH,wBAAgB,oCAAoC,CAClD,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,mBAAmB,CAAC,GACpE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CASlD"}

package/dist/lib/policy-fetch-cache.d.ts

@@ -0,0 +1,15 @@
+import { Policy } from '../types';
+interface PolicyFetchCache<T> {
+    readonly fetch: (policy: Policy) => Promise<T>;
+    readonly cache: Map<string, Promise<T>>;
+}
+/**
+ * Creates a per-instance cache that deduplicates in-flight requests by `policy.id`.
+ * The **Promise itself** is cached so concurrent callers share one request.
+ *
+ * Rejected promises are evicted so transient failures don't permanently
+ * poison the cache — the next call for the same `policy.id` retries.
+ */
+export declare function createPolicyFetchCache<T>(fetcher: (policy: Policy) => Promise<T>): PolicyFetchCache<T>;
+export {};
+//# sourceMappingURL=policy-fetch-cache.d.ts.map

package/dist/lib/policy-fetch-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-fetch-cache.d.ts","sourceRoot":"","sources":["../../src/lib/policy-fetch-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAEvC,UAAU,gBAAgB,CAAC,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;CACzC;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CActG"}

package/dist/types.d.ts

@@ -95,4 +95,8 @@ export type SaveOutput = {
     readonly flowExecution?: FlowExecution;
     readonly plansToUpdate?: readonly Plan[];
 };
+export interface PolicyDocumentation {
+    readonly content: string;
+    readonly language: 'MARKDOWN' | 'ASCIIDOC';
+}
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,OAAO,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE/F,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,WAAW,GAAG,cAAc,CAAC;AAEvH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;AAElG,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;AAEhD,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,WAAW,GAAG,MAAM,GAAG,KAAK,CAAC;AAE5E,8FAA8F;AAC9F,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;AAEhH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,eAAe,EAAE,QAAQ,GAAG,aAAa,CAAC;IACnD,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC,SAAS,GAAG,WAAW,CAAC,EAAE,CAAC;CAC5D;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,QAAQ,GAAG,aAAa,CAAC;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,MAAM,QAAQ,GAAG,eAAe,GAAG,iBAAiB,GAAG,YAAY,GAAG,WAAW,CAAC;AAExF,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,kBAAkB,CAAC;AAElG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,SAAS,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC;IACnG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,uBAAuB,GAAG;IACpC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACvC,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;CAC1C,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravitee/graphene-policy-studio",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0-alpha.2",
   "type": "module",
   "description": "Gravitee Policy Studio UI for the Graphene design system.",
   "keywords": [
@@ -30,7 +30,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "snippets",
+    "USAGE_GUIDE.md"
   ],
   "scripts": {
     "dev": "storybook dev -p 6008",

package/snippets/policy-studio-provider-host.tsx

@@ -0,0 +1,55 @@
+// Snippet: Policy Studio host provider wiring
+//
+// Use when embedding Policy Studio in an API management page and you own
+// the API data, fetchers, and save handler (provider host contract).
+// Do NOT use without real onFetchPolicySchema / onFetchPolicyDocumentation /
+// onSave implementations — the studio needs live host callbacks.
+//
+// Replace {PLACEHOLDERS} with your actual values.
+// See Storybook "Policy Studio/PolicyStudioProvider" for cache and save demos.
+
+import { useCallback, useMemo } from 'react';
+import { PolicyStudioProvider } from '@gravitee/graphene-policy-studio';
+import type { ApiType, Policy, SaveOutput } from '@gravitee/graphene-policy-studio';
+
+// 1. Build the page that wires host data and callbacks into the provider.
+export function ApiPolicyStudioPage({ apiType }: { apiType: ApiType }) {
+  const policies = useMemo(() => [] as const /* replace with policies from API */, []);
+  const plans = useMemo(() => [] as const /* replace with plans from API */, []);
+  const commonFlows = useMemo(() => [] as const /* replace with commonFlows from API */, []);
+  const sharedPolicyGroups = useMemo(() => [] as const /* replace with shared policy groups */, []);
+  const entrypointsInfo = useMemo(() => [] as const /* replace with entrypointsInfo */, []);
+  const endpointsInfo = useMemo(() => [] as const /* replace with endpointsInfo */, []);
+
+  const onSave = useCallback((_output: SaveOutput) => {
+    /* replace: persist SaveOutput delta to your API */
+  }, []);
+
+  const onFetchPolicySchema = useCallback(async (_policy: Policy) => {
+    /* replace: GET JSON schema for policy.id */
+    return {};
+  }, []);
+
+  const onFetchPolicyDocumentation = useCallback(async (_policy: Policy) => {
+    /* replace: GET docs (string or PolicyDocumentation) for policy.id */
+    return '';
+  }, []);
+
+  return (
+    <PolicyStudioProvider
+      apiType={apiType}
+      policies={policies}
+      sharedPolicyGroups={sharedPolicyGroups}
+      plans={plans}
+      commonFlows={commonFlows}
+      entrypointsInfo={entrypointsInfo}
+      endpointsInfo={endpointsInfo}
+      flowExecution={{ mode: 'DEFAULT' }}
+      onSave={onSave}
+      onFetchPolicySchema={onFetchPolicySchema}
+      onFetchPolicyDocumentation={onFetchPolicyDocumentation}
+    >
+      {null /* replace with studio UI (PolicyStudioLayout) or children using usePolicyStudioContext() */}
+    </PolicyStudioProvider>
+  );
+}