@almadar/ui 2.27.3 → 2.27.5

package/dist/flow/index.d.cts

@@ -0,0 +1,367 @@
+import React from 'react';
+import { NodeProps, Node, EdgeProps, Edge } from '@xyflow/react';
+import { State } from '@almadar/core';
+
+/**
+ * FlowPort Component
+ *
+ * Connection point rendered on a graph node. Shows a small circle that
+ * indicates whether the port is connected or available for wiring.
+ * Direction determines label placement (left for inputs, right for outputs).
+ */
+
+interface FlowPortProps {
+    /** Whether this port receives or sends connections. */
+    direction: 'in' | 'out';
+    /** Semantic type of the port (e.g. "string", "event", "entity"). */
+    portType: string;
+    /** Human-readable label shown beside the circle. */
+    label?: string;
+    /** Whether the port currently has a wire attached. */
+    connected?: boolean;
+    /** Whether a dragged wire is compatible with this port. */
+    compatible?: boolean;
+    className?: string;
+}
+/**
+ * A 12px circle with optional label indicating a node connection point.
+ * Outlined when disconnected, filled primary when connected, green ring when compatible.
+ */
+declare const FlowPort: React.FC<FlowPortProps>;
+
+/**
+ * FlowNodeShell Component
+ *
+ * Outer container for a graph node. Provides the card-like wrapper with a
+ * thin colored header bar, optional node-type label, and selection / warning
+ * ring states. Children are rendered in the body area below the header.
+ */
+
+interface FlowNodeShellProps {
+    /** Whether this node is currently selected on the canvas. */
+    selected?: boolean;
+    /** Whether this node has a validation warning. */
+    warning?: boolean;
+    /** Semantic node type label shown in the header (e.g. "Entity", "Trait"). */
+    nodeType?: string;
+    /** Background color for the 8px header bar. Any valid CSS color. */
+    headerColor?: string;
+    children: React.ReactNode;
+    className?: string;
+}
+/**
+ * Card-style wrapper for flow nodes with a colored header strip.
+ * Selection adds a solid primary ring; warnings show a dashed warning ring.
+ */
+declare const FlowNodeShell: React.FC<FlowNodeShellProps>;
+
+/**
+ * FlowLabel Component
+ *
+ * A pill-shaped label used on flow wires (edges) to annotate transitions,
+ * events, or guards. Supports truncation with a native title tooltip and
+ * semantic color variants.
+ */
+
+type FlowLabelVariant = 'default' | 'primary' | 'warning' | 'error';
+interface FlowLabelProps {
+    /** Text content of the label. */
+    text: string;
+    /** Max visible character count before truncation. Omit to show full text. */
+    truncate?: number;
+    /** Color variant mapping to Badge semantics. */
+    variant?: FlowLabelVariant;
+    className?: string;
+}
+/**
+ * Badge-based pill label for annotating wires in a flow graph.
+ * Long text is truncated with an ellipsis and full text appears on hover via title.
+ */
+declare const FlowLabel: React.FC<FlowLabelProps>;
+
+/**
+ * FlowWire Component
+ *
+ * Provides style objects and an SVG `<path>` wrapper for flow-graph edges.
+ * Wire colors come from the AVL CONNECTION_COLORS palette. The exported
+ * `getFlowWireStyle` helper can be used independently of the component
+ * (e.g. when integrating with React Flow edge renderers).
+ */
+
+type FlowWireType = 'transition' | 'event' | 'data' | 'guard';
+type FlowWireStatus = 'valid' | 'invalid' | 'pending';
+interface FlowWireProps {
+    /** Semantic wire category. Determines base color. */
+    wireType?: FlowWireType;
+    /** Validation or runtime status. 'invalid' overrides color to red. */
+    status?: FlowWireStatus;
+    /** Whether the wire shows a flowing dash animation. */
+    animated?: boolean;
+    /** SVG path data string (the "d" attribute). */
+    d?: string;
+    className?: string;
+}
+interface FlowWireStyle {
+    stroke: string;
+    strokeWidth: number;
+    strokeDasharray?: string;
+    animation?: string;
+}
+/**
+ * Compute SVG path style props for a flow wire.
+ *
+ * @returns An object suitable for spreading onto an SVG `<path>` element's style.
+ */
+declare function getFlowWireStyle(props: Pick<FlowWireProps, 'wireType' | 'status' | 'animated'>): FlowWireStyle;
+/**
+ * SVG path element styled as a flow wire.
+ * Pass the `d` prop with a path data string for rendering.
+ */
+declare const FlowWire: React.FC<FlowWireProps>;
+
+/**
+ * FlowMinimap Component
+ *
+ * A styled container that wraps a React Flow MiniMap at the organism level.
+ * Since atoms must not depend on React Flow, this component only provides the
+ * card-styled wrapper box and exports a color config object that organisms pass
+ * through to the MiniMap props.
+ */
+
+interface FlowMinimapProps {
+    /** Additional class names applied to the wrapper. */
+    className?: string;
+    children?: React.ReactNode;
+}
+/**
+ * Color tokens for the React Flow MiniMap component.
+ * Organisms import this and spread it onto `<MiniMap {...MINIMAP_COLORS} />`.
+ */
+declare const MINIMAP_COLORS: {
+    readonly nodeColor: "var(--color-primary, #3B82F6)";
+    readonly maskColor: "var(--color-background, #ffffff80)";
+    readonly nodeStrokeColor: "var(--color-border, #E5E7EB)";
+};
+/**
+ * Card-styled wrapper for the React Flow MiniMap.
+ * Render the actual `<MiniMap>` component as children at the organism level.
+ */
+declare const FlowMinimap: React.FC<FlowMinimapProps>;
+
+/**
+ * FlowStateNode Component
+ *
+ * Custom React Flow node for a state machine state.
+ * Renders a FlowNodeShell with role-based header color, state name,
+ * and initial/terminal badges. Handles are placed at top (target)
+ * and bottom (source) for vertical transition wiring.
+ */
+
+/** React Flow node type for state machine states, backed by @almadar/core State. */
+type StateFlowNode = Node<State & Record<string, unknown>, 'state'>;
+/**
+ * React Flow custom node that visualises a single state machine state.
+ * Uses STATE_COLORS for the header bar and shows role badges.
+ */
+declare const FlowStateNode: React.FC<NodeProps<StateFlowNode>>;
+
+/**
+ * OrbitalNode Component
+ *
+ * Custom React Flow node for an orbital unit. Displays entity name,
+ * trait/page counts, and per-event Handles for emit (source, right)
+ * and listen (target, left) wiring.
+ */
+
+/** Data shape for orbital flow nodes, extending Record<string, unknown> for React Flow v12. */
+interface OrbitalNodeData extends Record<string, unknown> {
+    /** Orbital unit name. */
+    name: string;
+    /** Primary entity name. */
+    entityName: string;
+    /** Number of traits attached. */
+    traitCount: number;
+    /** Number of pages attached. */
+    pageCount: number;
+    /** Events this orbital emits. */
+    emits: string[];
+    /** Events this orbital listens for. */
+    listens: string[];
+}
+/** React Flow node type for orbital units. */
+type OrbitalFlowNode = Node<OrbitalNodeData, 'orbital'>;
+/**
+ * React Flow custom node for an orbital unit showing entity info,
+ * trait/page stats, and per-event connection handles.
+ */
+declare const OrbitalNode: React.FC<NodeProps<OrbitalFlowNode>>;
+
+/**
+ * BehaviorNode Component
+ *
+ * Custom React Flow node for a standard behavior. Shows name,
+ * truncated description, state count, and per-event Handles for
+ * emit (source, right) and listen (target, left) wiring.
+ */
+
+/** Data shape for behavior flow nodes, extending Record<string, unknown> for React Flow v12. */
+interface BehaviorNodeData extends Record<string, unknown> {
+    /** Behavior name (e.g. "std-cart"). */
+    name: string;
+    /** Optional description, truncated after 60 chars. */
+    description?: string;
+    /** Number of states in this behavior. */
+    stateCount: number;
+    /** Events this behavior emits. */
+    emits: string[];
+    /** Events this behavior listens for. */
+    listens: string[];
+}
+/** React Flow node type for behavior nodes. */
+type BehaviorFlowNode = Node<BehaviorNodeData, 'behavior'>;
+/**
+ * React Flow custom node for a standard behavior with event port handles.
+ */
+declare const BehaviorNode: React.FC<NodeProps<BehaviorFlowNode>>;
+
+type AvlOperatorNamespace = 'arithmetic' | 'comparison' | 'logic' | 'string' | 'collection' | 'time' | 'control' | 'async';
+type EffectCategory = 'ui' | 'data' | 'communication' | 'lifecycle' | 'control';
+
+/**
+ * ExprNode Component
+ *
+ * Custom React Flow node for an S-expression operator.
+ * Shows the operator name in namespace-colored FlowNodeShell,
+ * with one target Handle per operand (left, staggered) and
+ * one source Handle for the result (right).
+ */
+
+/** Data shape for expression flow nodes, extending Record<string, unknown> for React Flow v12. */
+interface ExprNodeData extends Record<string, unknown> {
+    /** Operator name (e.g. "+", "concat", "if"). */
+    operator: string;
+    /** Operator namespace for color coding. */
+    namespace?: AvlOperatorNamespace;
+    /** Number of operand inputs. */
+    operandCount: number;
+}
+/** React Flow node type for S-expression operator nodes. */
+type ExprFlowNode = Node<ExprNodeData, 'expr'>;
+/**
+ * React Flow custom node visualising an S-expression operator.
+ * Operand handles fan out vertically on the left; result exits right.
+ */
+declare const ExprNode: React.FC<NodeProps<ExprFlowNode>>;
+
+/**
+ * EffectNode Component
+ *
+ * Custom React Flow node for an effect in a transition.
+ * Shows the effect type with a category-colored header and
+ * optional args caption. One target Handle (left) for input,
+ * one source Handle (right) for chain output.
+ */
+
+/** Data shape for effect flow nodes, extending Record<string, unknown> for React Flow v12. */
+interface EffectNodeData extends Record<string, unknown> {
+    /** Effect type identifier (e.g. "render-ui", "set", "emit"). */
+    effectType: string;
+    /** Optional stringified args summary. */
+    args?: string;
+    /** Category override. Derived from effectType when omitted. */
+    category?: EffectCategory;
+}
+/** React Flow node type for effect nodes in transition chains. */
+type EffectFlowNode = Node<EffectNodeData, 'effect'>;
+/**
+ * React Flow custom node for an effect in a transition chain.
+ */
+declare const EffectNode: React.FC<NodeProps<EffectFlowNode>>;
+
+/**
+ * TransitionEdge Component
+ *
+ * Custom React Flow edge for state machine transitions.
+ * Uses a Bezier path with a FlowLabel pill at the midpoint showing
+ * the event name. Guard (diamond) and effect indicators are shown
+ * as small inline icons beside the label.
+ */
+
+/** Data shape for transition flow edges, extending Record<string, unknown> for React Flow v12. */
+interface TransitionEdgeData extends Record<string, unknown> {
+    /** Triggering event name. */
+    event: string;
+    /** Whether this transition has a guard condition. */
+    hasGuard?: boolean;
+    /** Whether this transition has effects attached. */
+    hasEffects?: boolean;
+}
+/** React Flow edge type for state machine transitions. */
+type TransitionFlowEdge = Edge<TransitionEdgeData, 'transition'>;
+/**
+ * React Flow custom edge that renders a Bezier curve with an event label pill.
+ * Guard and effect presence are shown as small indicator icons.
+ */
+declare const TransitionEdge: React.FC<EdgeProps<TransitionFlowEdge>>;
+
+/**
+ * EventWireEdge Component
+ *
+ * Custom React Flow edge for event wiring between orbitals/behaviors.
+ * Renders a dashed orange Bezier path (from CONNECTION_COLORS.emitListen)
+ * with a FlowLabel pill at the midpoint. Incompatible wires turn red.
+ */
+
+/** Data shape for event wire flow edges, extending Record<string, unknown> for React Flow v12. */
+interface EventWireEdgeData extends Record<string, unknown> {
+    /** Event name being wired. */
+    event: string;
+    /** Whether emitter and listener schemas are compatible. */
+    compatible?: boolean;
+}
+/** React Flow edge type for emit/listen event wiring. */
+type EventWireFlowEdge = Edge<EventWireEdgeData, 'eventWire'>;
+/**
+ * React Flow custom edge for emit/listen event wiring.
+ * Dashed orange when compatible, dashed red when incompatible.
+ */
+declare const EventWireEdge: React.FC<EdgeProps<EventWireFlowEdge>>;
+
+/**
+ * NodePalette Component
+ *
+ * Draggable node type sidebar for a flow editor. Renders categories of
+ * tiles that can be dragged onto a React Flow canvas. Each tile sets
+ * `application/reactflow` data on the drag transfer so the canvas
+ * `onDrop` handler knows which node type to create.
+ *
+ * This is a pure HTML component with no React Flow imports.
+ */
+
+interface NodePaletteItem {
+    /** Node type identifier set on the drag transfer. */
+    type: string;
+    /** Human-readable label shown on the tile. */
+    label: string;
+    /** Lucide icon name for the tile. */
+    icon: string;
+}
+interface NodePaletteCategory {
+    /** Category heading. */
+    name: string;
+    /** Draggable items in this category. */
+    items: NodePaletteItem[];
+}
+interface NodePaletteProps {
+    /** Grouped node types available for dragging. */
+    categories: NodePaletteCategory[];
+    /** Additional CSS classes on the outer container. */
+    className?: string;
+}
+/**
+ * Sidebar palette of draggable node tiles grouped by category.
+ * Drag a tile onto a ReactFlow canvas to create that node type.
+ */
+declare const NodePalette: React.FC<NodePaletteProps>;
+
+export { type BehaviorFlowNode, BehaviorNode, type BehaviorNodeData, type EffectFlowNode, EffectNode, type EffectNodeData, EventWireEdge, type EventWireEdgeData, type EventWireFlowEdge, type ExprFlowNode, ExprNode, type ExprNodeData, FlowLabel, type FlowLabelProps, type FlowLabelVariant, FlowMinimap, type FlowMinimapProps, FlowNodeShell, type FlowNodeShellProps, FlowPort, type FlowPortProps, FlowStateNode, FlowWire, type FlowWireProps, type FlowWireStatus, type FlowWireStyle, type FlowWireType, MINIMAP_COLORS, NodePalette, type NodePaletteCategory, type NodePaletteProps, type OrbitalFlowNode, OrbitalNode, type OrbitalNodeData, type StateFlowNode, TransitionEdge, type TransitionEdgeData, type TransitionFlowEdge, getFlowWireStyle };

package/dist/flow/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @almadar/ui/flow
+ *
+ * OrbitalFlow — React Flow-based interactive graph editor for .orb structures.
+ * Atoms are pure visual primitives. Molecules are custom React Flow node/edge types.
+ */
+export { FlowPort, type FlowPortProps, FlowNodeShell, type FlowNodeShellProps, FlowLabel, type FlowLabelProps, type FlowLabelVariant, FlowWire, type FlowWireProps, type FlowWireType, type FlowWireStatus, type FlowWireStyle, getFlowWireStyle, FlowMinimap, type FlowMinimapProps, MINIMAP_COLORS, } from '../components/atoms/flow';
+export { FlowStateNode, type StateFlowNode, OrbitalNode, type OrbitalNodeData, type OrbitalFlowNode, BehaviorNode, type BehaviorNodeData, type BehaviorFlowNode, ExprNode, type ExprNodeData, type ExprFlowNode, EffectNode, type EffectNodeData, type EffectFlowNode, } from '../components/molecules/flow';
+export { TransitionEdge, type TransitionEdgeData, type TransitionFlowEdge, EventWireEdge, type EventWireEdgeData, type EventWireFlowEdge, } from '../components/molecules/flow';
+export { NodePalette, type NodePaletteProps, type NodePaletteCategory, } from '../components/molecules/flow';