@01.software/sdk 0.5.1 → 0.5.3

package/dist/ui/flow.d.cts

@@ -1,13 +1,10 @@
-import { N as NodeTypeDef, E as EdgeTypeDef, C as CanvasData, F as FlowNode, D as DynamicNodeSlotProps, a as FlowEdge, b as FrameNodeSlotProps, c as EdgeSlotProps, d as NodeWrapperSlotProps, e as FlowViewport, f as FlowBounds } from '../server-B80o7igg.cjs';
-export { i as DynamicNodeData, h as FlowNodeData, g as FlowNodePosition, s as FrameData, j as FrameNodeData, k as NodeTypeFieldDef, P as PrefetchFlowOptions, S as SDKClient, U as UseFlowOptions, n as UseFlowResult, r as getFrameData, q as getFrames, o as getNodeBounds, l as isDynamicNode, m as isFrameNode, p as prefetchFlow, u as useFlow } from '../server-B80o7igg.cjs';
+import { C as CanvasData, N as NodeTypeDef, E as EdgeTypeDef, F as FlowNode, a as NodeTypeFieldDef, D as DynamicNodeSlotProps, b as FlowEdge, c as FrameNodeSlotProps, d as EdgeSlotProps, e as NodeWrapperSlotProps, f as FlowViewport, g as FlowBounds, S as SDKClient, h as FrameData } from '../server-StNHlSjW.cjs';
+export { o as BUILT_IN_EDGE_TYPES, B as BUILT_IN_NODE_TYPES, k as DynamicNodeData, j as FlowNodeData, i as FlowNodePosition, l as FrameNodeData, P as PrefetchFlowOptions, U as UseFlowOptions, p as UseFlowResult, t as getFrameData, s as getFrames, r as getNodeBounds, m as isDynamicNode, n as isFrameNode, q as prefetchFlow, u as useFlow } from '../server-StNHlSjW.cjs';
 import { Edge } from '@xyflow/react';
 import React from 'react';
+import { I as ImageData } from '../image-TT8lTsk5.cjs';
 import '@tanstack/react-query';
 
-declare const BUILT_IN_NODE_TYPES: NodeTypeDef[];
-
-declare const BUILT_IN_EDGE_TYPES: EdgeTypeDef[];
-
 interface UseFlowDataOptions {
     /** Canvas data from Flow document's `canvas` field */
     data: CanvasData | undefined;
@@ -44,6 +41,31 @@ interface CodeComponentProps {
 declare function compileTemplate(code: string, slug: string): React.FC<CodeComponentProps> | null;
 declare function clearTemplateCache(): void;
 
+declare function renderFieldValue(key: string, val: unknown, fieldDef?: NodeTypeFieldDef): React.ReactNode;
+
+/** Extract an image field value with proper typing. */
+declare function getImageField(fields: Record<string, unknown>, name: string): ImageData | undefined;
+/** Extract a text/textarea/url/color field value. */
+declare function getTextField(fields: Record<string, unknown>, name: string): string | undefined;
+/** Extract a number field value. */
+declare function getNumberField(fields: Record<string, unknown>, name: string): number | undefined;
+/** Extract a toggle/boolean field value. */
+declare function getBooleanField(fields: Record<string, unknown>, name: string): boolean | undefined;
+
+/**
+ * Sanitize tenant-authored CSS using PostCSS AST parsing.
+ *
+ * - At-rules: allowlist only (@keyframes, @media, @supports, @container, @layer)
+ * - Declarations: blocks url(), expression(), paint(), -moz-binding
+ * - Selectors: removes :root/html/body targets; scopes remainder under scopeClass
+ *
+ * Returns empty string on parse failure (fail-closed).
+ *
+ * @param css - Raw CSS string from tenant
+ * @param scopeClass - Container class to scope selectors (e.g. 'flow-node--my-type')
+ */
+declare function sanitizeCSS(css: string, scopeClass?: string): string;
+
 /**
  * Renders a Flow canvas in read-only mode.
  *
@@ -83,11 +105,13 @@ interface FlowRendererProps {
     onNodeMouseLeave?: (event: React.MouseEvent, node: FlowNode) => void;
     /** Called when an edge is clicked */
     onEdgeClick?: (event: React.MouseEvent, edge: FlowEdge) => void;
-    /** S1: Custom frame node renderer. Should be a stable reference (memoize or define outside render). */
+    /** S1: Custom frame node renderer */
     frameRenderer?: React.ComponentType<FrameNodeSlotProps>;
-    /** S2: Custom edge renderers by edge type slug. Should be a stable reference (memoize or define outside render). */
+    /** Hide frame nodes. Shorthand for `frameRenderer={() => null}`. Default: false */
+    hideFrames?: boolean;
+    /** S2: Custom edge renderers by edge type slug */
     edgeRenderers?: Record<string, React.ComponentType<EdgeSlotProps>>;
-    /** S3: Wraps every dynamic node's rendered content. Should be a stable reference (memoize or define outside render). */
+    /** S3: Wraps every dynamic node's rendered content */
     nodeWrapper?: React.ComponentType<NodeWrapperSlotProps>;
     /** S4: Show controls (default: false) */
     controls?: boolean;
@@ -122,6 +146,48 @@ interface FlowRendererProps {
     /** Maximum zoom level */
     maxZoom?: number;
 }
-declare function FlowRenderer({ data, className, style, nodeRenderers, nodeTypeDefs, edgeTypeDefs, background, interactive, fitView, onNodeClick, onNodeDoubleClick, onNodeContextMenu, onNodeMouseEnter, onNodeMouseLeave, onEdgeClick, frameRenderer, edgeRenderers, nodeWrapper, controls, minimap, minimapNodeColor, children, renderNode, onViewportChange, defaultViewport: defaultViewportProp, bounds, clampBounds, focusPadding, focusAnimation, focusMode, responsiveFit, translateExtent: translateExtentProp, minZoom: minZoomProp, maxZoom: maxZoomProp, }: FlowRendererProps): React.JSX.Element | null;
+declare function FlowRenderer({ data, className, style, nodeRenderers, nodeTypeDefs, edgeTypeDefs, background, interactive, fitView, onNodeClick, onNodeDoubleClick, onNodeContextMenu, onNodeMouseEnter, onNodeMouseLeave, onEdgeClick, frameRenderer, hideFrames, edgeRenderers, nodeWrapper, controls, minimap, minimapNodeColor, children, renderNode, onViewportChange, defaultViewport: defaultViewportProp, bounds, clampBounds, focusPadding, focusAnimation, focusMode, responsiveFit, translateExtent: translateExtentProp, minZoom: minZoomProp, maxZoom: maxZoomProp, }: FlowRendererProps): React.JSX.Element | null;
+
+interface FlowFrameProps extends Omit<FlowRendererProps, 'data' | 'nodeTypeDefs' | 'edgeTypeDefs' | 'bounds' | 'clampBounds' | 'fitView' | 'hideFrames' | 'translateExtent' | 'defaultViewport'> {
+    /** SDK client instance (Client or ServerClient) */
+    client: SDKClient;
+    /** Flow slug (URL-friendly identifier) */
+    slug?: string;
+    /** Flow document ID (UUID) */
+    id?: string;
+    /** Frame node ID to render */
+    frameId: string;
+    /** Content rendered while loading (default: null) */
+    loading?: React.ReactNode;
+    /** Render function for error state (default: returns null) */
+    error?: (err: Error) => React.ReactNode;
+    /**
+     * Called when frame data is ready — escape hatch for raw data access.
+     * Use `prefetchFlow({ client, slug })` for SSR.
+     */
+    onDataReady?: (frameData: FrameData, flow: Record<string, unknown>) => void;
+}
+/**
+ * Renders a single frame from a Flow document.
+ *
+ * Fetches the flow via `useFlow`, extracts the frame with `getFrameData`,
+ * and passes the result to `FlowRenderer` with correct bounds wired.
+ *
+ * For SSR / prefetching use the existing `prefetchFlow({ client, slug })`.
+ *
+ * @example
+ * ```tsx
+ * import { FlowFrame } from '@01.software/sdk/ui/flow'
+ *
+ * export default function Home() {
+ *   return (
+ *     <div className="w-full h-screen">
+ *       <FlowFrame client={client} slug="home" frameId={FRAME_ID} interactive />
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function FlowFrame({ client, slug, id, frameId, loading, error: renderError, onDataReady, ...rendererProps }: FlowFrameProps): React.JSX.Element | null;
 
-export { BUILT_IN_EDGE_TYPES, BUILT_IN_NODE_TYPES, CanvasData, type CodeComponentProps, DynamicNodeSlotProps, EdgeSlotProps, EdgeTypeDef, FlowBounds, FlowEdge, FlowNode, FlowRenderer, type FlowRendererProps, FlowViewport, FrameNodeSlotProps, NodeTypeDef, NodeWrapperSlotProps, type UseFlowDataOptions, type UseFlowDataResult, clearTemplateCache, compileTemplate, useFlowData };
+export { CanvasData, type CodeComponentProps, DynamicNodeSlotProps, EdgeSlotProps, EdgeTypeDef, FlowBounds, FlowEdge, FlowFrame, type FlowFrameProps, FlowNode, FlowRenderer, type FlowRendererProps, FlowViewport, FrameData, FrameNodeSlotProps, NodeTypeDef, NodeTypeFieldDef, NodeWrapperSlotProps, SDKClient, type UseFlowDataOptions, type UseFlowDataResult, clearTemplateCache, compileTemplate, getBooleanField, getImageField, getNumberField, getTextField, renderFieldValue, sanitizeCSS, useFlowData };

package/dist/ui/flow.d.ts

@@ -1,13 +1,10 @@
-import { N as NodeTypeDef, E as EdgeTypeDef, C as CanvasData, F as FlowNode, D as DynamicNodeSlotProps, a as FlowEdge, b as FrameNodeSlotProps, c as EdgeSlotProps, d as NodeWrapperSlotProps, e as FlowViewport, f as FlowBounds } from '../server-B80o7igg.js';
-export { i as DynamicNodeData, h as FlowNodeData, g as FlowNodePosition, s as FrameData, j as FrameNodeData, k as NodeTypeFieldDef, P as PrefetchFlowOptions, S as SDKClient, U as UseFlowOptions, n as UseFlowResult, r as getFrameData, q as getFrames, o as getNodeBounds, l as isDynamicNode, m as isFrameNode, p as prefetchFlow, u as useFlow } from '../server-B80o7igg.js';
+import { C as CanvasData, N as NodeTypeDef, E as EdgeTypeDef, F as FlowNode, a as NodeTypeFieldDef, D as DynamicNodeSlotProps, b as FlowEdge, c as FrameNodeSlotProps, d as EdgeSlotProps, e as NodeWrapperSlotProps, f as FlowViewport, g as FlowBounds, S as SDKClient, h as FrameData } from '../server-StNHlSjW.js';
+export { o as BUILT_IN_EDGE_TYPES, B as BUILT_IN_NODE_TYPES, k as DynamicNodeData, j as FlowNodeData, i as FlowNodePosition, l as FrameNodeData, P as PrefetchFlowOptions, U as UseFlowOptions, p as UseFlowResult, t as getFrameData, s as getFrames, r as getNodeBounds, m as isDynamicNode, n as isFrameNode, q as prefetchFlow, u as useFlow } from '../server-StNHlSjW.js';
 import { Edge } from '@xyflow/react';
 import React from 'react';
+import { I as ImageData } from '../image-TT8lTsk5.js';
 import '@tanstack/react-query';
 
-declare const BUILT_IN_NODE_TYPES: NodeTypeDef[];
-
-declare const BUILT_IN_EDGE_TYPES: EdgeTypeDef[];
-
 interface UseFlowDataOptions {
     /** Canvas data from Flow document's `canvas` field */
     data: CanvasData | undefined;
@@ -44,6 +41,31 @@ interface CodeComponentProps {
 declare function compileTemplate(code: string, slug: string): React.FC<CodeComponentProps> | null;
 declare function clearTemplateCache(): void;
 
+declare function renderFieldValue(key: string, val: unknown, fieldDef?: NodeTypeFieldDef): React.ReactNode;
+
+/** Extract an image field value with proper typing. */
+declare function getImageField(fields: Record<string, unknown>, name: string): ImageData | undefined;
+/** Extract a text/textarea/url/color field value. */
+declare function getTextField(fields: Record<string, unknown>, name: string): string | undefined;
+/** Extract a number field value. */
+declare function getNumberField(fields: Record<string, unknown>, name: string): number | undefined;
+/** Extract a toggle/boolean field value. */
+declare function getBooleanField(fields: Record<string, unknown>, name: string): boolean | undefined;
+
+/**
+ * Sanitize tenant-authored CSS using PostCSS AST parsing.
+ *
+ * - At-rules: allowlist only (@keyframes, @media, @supports, @container, @layer)
+ * - Declarations: blocks url(), expression(), paint(), -moz-binding
+ * - Selectors: removes :root/html/body targets; scopes remainder under scopeClass
+ *
+ * Returns empty string on parse failure (fail-closed).
+ *
+ * @param css - Raw CSS string from tenant
+ * @param scopeClass - Container class to scope selectors (e.g. 'flow-node--my-type')
+ */
+declare function sanitizeCSS(css: string, scopeClass?: string): string;
+
 /**
  * Renders a Flow canvas in read-only mode.
  *
@@ -83,11 +105,13 @@ interface FlowRendererProps {
     onNodeMouseLeave?: (event: React.MouseEvent, node: FlowNode) => void;
     /** Called when an edge is clicked */
     onEdgeClick?: (event: React.MouseEvent, edge: FlowEdge) => void;
-    /** S1: Custom frame node renderer. Should be a stable reference (memoize or define outside render). */
+    /** S1: Custom frame node renderer */
     frameRenderer?: React.ComponentType<FrameNodeSlotProps>;
-    /** S2: Custom edge renderers by edge type slug. Should be a stable reference (memoize or define outside render). */
+    /** Hide frame nodes. Shorthand for `frameRenderer={() => null}`. Default: false */
+    hideFrames?: boolean;
+    /** S2: Custom edge renderers by edge type slug */
     edgeRenderers?: Record<string, React.ComponentType<EdgeSlotProps>>;
-    /** S3: Wraps every dynamic node's rendered content. Should be a stable reference (memoize or define outside render). */
+    /** S3: Wraps every dynamic node's rendered content */
     nodeWrapper?: React.ComponentType<NodeWrapperSlotProps>;
     /** S4: Show controls (default: false) */
     controls?: boolean;
@@ -122,6 +146,48 @@ interface FlowRendererProps {
     /** Maximum zoom level */
     maxZoom?: number;
 }
-declare function FlowRenderer({ data, className, style, nodeRenderers, nodeTypeDefs, edgeTypeDefs, background, interactive, fitView, onNodeClick, onNodeDoubleClick, onNodeContextMenu, onNodeMouseEnter, onNodeMouseLeave, onEdgeClick, frameRenderer, edgeRenderers, nodeWrapper, controls, minimap, minimapNodeColor, children, renderNode, onViewportChange, defaultViewport: defaultViewportProp, bounds, clampBounds, focusPadding, focusAnimation, focusMode, responsiveFit, translateExtent: translateExtentProp, minZoom: minZoomProp, maxZoom: maxZoomProp, }: FlowRendererProps): React.JSX.Element | null;
+declare function FlowRenderer({ data, className, style, nodeRenderers, nodeTypeDefs, edgeTypeDefs, background, interactive, fitView, onNodeClick, onNodeDoubleClick, onNodeContextMenu, onNodeMouseEnter, onNodeMouseLeave, onEdgeClick, frameRenderer, hideFrames, edgeRenderers, nodeWrapper, controls, minimap, minimapNodeColor, children, renderNode, onViewportChange, defaultViewport: defaultViewportProp, bounds, clampBounds, focusPadding, focusAnimation, focusMode, responsiveFit, translateExtent: translateExtentProp, minZoom: minZoomProp, maxZoom: maxZoomProp, }: FlowRendererProps): React.JSX.Element | null;
+
+interface FlowFrameProps extends Omit<FlowRendererProps, 'data' | 'nodeTypeDefs' | 'edgeTypeDefs' | 'bounds' | 'clampBounds' | 'fitView' | 'hideFrames' | 'translateExtent' | 'defaultViewport'> {
+    /** SDK client instance (Client or ServerClient) */
+    client: SDKClient;
+    /** Flow slug (URL-friendly identifier) */
+    slug?: string;
+    /** Flow document ID (UUID) */
+    id?: string;
+    /** Frame node ID to render */
+    frameId: string;
+    /** Content rendered while loading (default: null) */
+    loading?: React.ReactNode;
+    /** Render function for error state (default: returns null) */
+    error?: (err: Error) => React.ReactNode;
+    /**
+     * Called when frame data is ready — escape hatch for raw data access.
+     * Use `prefetchFlow({ client, slug })` for SSR.
+     */
+    onDataReady?: (frameData: FrameData, flow: Record<string, unknown>) => void;
+}
+/**
+ * Renders a single frame from a Flow document.
+ *
+ * Fetches the flow via `useFlow`, extracts the frame with `getFrameData`,
+ * and passes the result to `FlowRenderer` with correct bounds wired.
+ *
+ * For SSR / prefetching use the existing `prefetchFlow({ client, slug })`.
+ *
+ * @example
+ * ```tsx
+ * import { FlowFrame } from '@01.software/sdk/ui/flow'
+ *
+ * export default function Home() {
+ *   return (
+ *     <div className="w-full h-screen">
+ *       <FlowFrame client={client} slug="home" frameId={FRAME_ID} interactive />
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function FlowFrame({ client, slug, id, frameId, loading, error: renderError, onDataReady, ...rendererProps }: FlowFrameProps): React.JSX.Element | null;
 
-export { BUILT_IN_EDGE_TYPES, BUILT_IN_NODE_TYPES, CanvasData, type CodeComponentProps, DynamicNodeSlotProps, EdgeSlotProps, EdgeTypeDef, FlowBounds, FlowEdge, FlowNode, FlowRenderer, type FlowRendererProps, FlowViewport, FrameNodeSlotProps, NodeTypeDef, NodeWrapperSlotProps, type UseFlowDataOptions, type UseFlowDataResult, clearTemplateCache, compileTemplate, useFlowData };
+export { CanvasData, type CodeComponentProps, DynamicNodeSlotProps, EdgeSlotProps, EdgeTypeDef, FlowBounds, FlowEdge, FlowFrame, type FlowFrameProps, FlowNode, FlowRenderer, type FlowRendererProps, FlowViewport, FrameData, FrameNodeSlotProps, NodeTypeDef, NodeTypeFieldDef, NodeWrapperSlotProps, SDKClient, type UseFlowDataOptions, type UseFlowDataResult, clearTemplateCache, compileTemplate, getBooleanField, getImageField, getNumberField, getTextField, renderFieldValue, sanitizeCSS, useFlowData };