vizmatic 0.1.42 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -74,8 +74,8 @@ type ToneName = 'blue' | 'purple' | 'green' | 'warm' | 'cyan' | 'pink' | 'red' |
74
74
  declare const toneGradients: Record<ToneName, string>;
75
75
  declare function getToneGradient(tone: ToneName): string;
76
76
  declare function getToneColor(tone: ToneName, c: ThemeColors): string;
77
- /** Get a tone variant that remains readable as text in either theme. */
78
- declare function getReadableToneColor(tone: ToneName, c: ThemeColors, background?: string): string;
77
+ /** Get a tone variant that remains readable against the background over its backdrop. */
78
+ declare function getReadableToneColor(tone: ToneName, c: ThemeColors, background?: string, backdrop?: string): string;
79
79
  /** Low-chroma fills for diagrams. The engineering preset uses opaque pastels. */
80
80
  declare function getToneFill(tone: ToneName, c: ThemeColors): string;
81
81
  declare const typography: {
@@ -207,8 +207,8 @@ type ColorName = 'primary' | 'secondary' | 'positive' | 'warning' | 'critical' |
207
207
  declare function getColor(name: ColorName, c?: ThemeColors): string;
208
208
  /** Get a semantic color variant that remains readable as text in either theme. */
209
209
  declare function getReadableColor(name: ColorName, c: ThemeColors): string;
210
- /** Choose readable foreground text for a solid theme color. */
211
- declare function getReadableTextColor(background: string, c: ThemeColors): string;
210
+ /** Choose readable foreground text, compositing translucent backgrounds over their backdrop. */
211
+ declare function getReadableTextColor(background: string, c: ThemeColors, backdrop?: string): string;
212
212
  /**
213
213
  * Get a gradient by semantic name.
214
214
  * Gradients are the same for both themes (they sit on top of content
@@ -831,6 +831,8 @@ interface GraphDiagramNode {
831
831
  id: string;
832
832
  label: React.ReactNode;
833
833
  detail?: React.ReactNode;
834
+ href?: string;
835
+ title?: string;
834
836
  x?: number;
835
837
  y?: number;
836
838
  tone?: ToneName;
@@ -865,6 +867,7 @@ type GraphDiagramEdgeKind = 'sync' | 'async' | 'event' | 'data' | 'dependency' |
865
867
  type GraphDiagramEdgeStyle = 'solid' | 'dashed' | 'dotted';
866
868
  type GraphDiagramEdgeArrow = 'forward' | 'backward' | 'both' | 'none';
867
869
  interface GraphDiagramEdge {
870
+ id?: string;
868
871
  from: string;
869
872
  to: string;
870
873
  tone?: ToneName;
@@ -874,6 +877,8 @@ interface GraphDiagramEdge {
874
877
  kind?: GraphDiagramEdgeKind;
875
878
  style?: GraphDiagramEdgeStyle;
876
879
  arrow?: GraphDiagramEdgeArrow;
880
+ href?: string;
881
+ title?: string;
877
882
  }
878
883
  interface GraphDiagramProps {
879
884
  nodes: GraphDiagramNode[];
@@ -895,9 +900,12 @@ interface GraphDiagramProps {
895
900
  edgeGap?: number;
896
901
  sizing?: 'content' | 'fixed';
897
902
  iconSize?: number;
903
+ id?: string;
898
904
  ariaLabel?: string;
905
+ title?: string;
906
+ description?: string;
899
907
  }
900
- declare function GraphDiagram({ nodes, edges, groups, c, width, height, nodeWidth, nodeHeight, labelFontSize, detailFontSize, arrowSize, padding, layout: requestedLayout, direction, nodeGap, rankGap, edgeGap, sizing, iconSize, ariaLabel, }: GraphDiagramProps): React.ReactElement;
908
+ declare function GraphDiagram({ nodes, edges, groups, c, width, height, nodeWidth, nodeHeight, labelFontSize, detailFontSize, arrowSize, padding, layout: requestedLayout, direction, nodeGap, rankGap, edgeGap, sizing, iconSize, id, ariaLabel, title, description, }: GraphDiagramProps): React.ReactElement;
901
909
  interface TreeNodeSpec {
902
910
  label: React.ReactNode;
903
911
  id?: string;
@@ -1055,6 +1063,8 @@ interface DataflowNode {
1055
1063
  id: string;
1056
1064
  label: React.ReactNode;
1057
1065
  detail?: React.ReactNode;
1066
+ href?: string;
1067
+ title?: string;
1058
1068
  kind: DataflowNodeKind;
1059
1069
  schema?: DataflowSchema;
1060
1070
  tone?: ToneName;
@@ -1065,9 +1075,12 @@ interface DataflowNode {
1065
1075
  height?: number;
1066
1076
  }
1067
1077
  interface DataflowEdge {
1078
+ id?: string;
1068
1079
  from: string;
1069
1080
  to: string;
1070
1081
  label?: string;
1082
+ href?: string;
1083
+ title?: string;
1071
1084
  schema?: DataflowSchema;
1072
1085
  mode?: DataflowEdgeMode;
1073
1086
  tone?: ToneName;
@@ -1086,6 +1099,9 @@ interface DataflowSpec {
1086
1099
  edges: DataflowEdge[];
1087
1100
  boundaries?: DataflowBoundary[];
1088
1101
  ariaLabel?: string;
1102
+ id?: string;
1103
+ title?: string;
1104
+ description?: string;
1089
1105
  }
1090
1106
  interface DataflowDiagramProps extends DataflowSpec {
1091
1107
  c: ThemeColors;
@@ -1105,7 +1121,7 @@ interface DataflowDiagramProps extends DataflowSpec {
1105
1121
  iconSize?: number;
1106
1122
  }
1107
1123
  /** Render typed dataflow nodes and edges through the existing GraphDiagram. */
1108
- declare function DataflowDiagram({ c, nodes, edges, boundaries, ariaLabel, width, height, nodeWidth, nodeHeight, labelFontSize, detailFontSize, arrowSize, padding, direction, nodeGap, rankGap, edgeGap, sizing, iconSize, }: DataflowDiagramProps): React.ReactElement;
1124
+ declare function DataflowDiagram({ c, nodes, edges, boundaries, ariaLabel, id, title, description, width, height, nodeWidth, nodeHeight, labelFontSize, detailFontSize, arrowSize, padding, direction, nodeGap, rankGap, edgeGap, sizing, iconSize, }: DataflowDiagramProps): React.ReactElement;
1109
1125
 
1110
1126
  /** Deployment boundary kinds understood by {@link DeploymentDiagram}. */
1111
1127
  type DeploymentBoundaryKind = 'region' | 'zone' | 'vpc' | 'subnet' | 'namespace' | 'host' | 'cluster' | 'trust';
@@ -1987,4 +2003,144 @@ declare function renderAnimatedGifWithOutput(scenes: AnimatedScene[], options: A
1987
2003
  declare function renderAnimationGif<S extends object>(animation: DefinedAnimation<S>, options: AnimationOptions): Promise<void>;
1988
2004
  declare function renderAnimationGifWithOutput<S extends object>(animation: DefinedAnimation<S>, options: AnimationOptions): Promise<AnimationOutput>;
1989
2005
 
1990
- export { type AnimatedScene, type AnimationCadenceAnalysis, type AnimationDefinition, type AnimationEasing, type AnimationEasingName, type AnimationFrameContext, type AnimationHoldStep, type AnimationInterpolator, type AnimationKeyframeStep, type AnimationOptions, type AnimationOutput, type AnimationOverflowContext, type AnimationParallelStep, type AnimationParallelTracks, type AnimationPropertyStep, type AnimationTimelineStep, type AnimationTweenStep, Arrow, ArrowMarkerDef, AxisPlot, type AxisPlotPath, type AxisPlotPoint, type AxisPlotVector, Badge, BadgePill, BarChart, type BarChartDatum, Box, CalloutCard, Canvas, CanvasOverflowError, Card, ChartFrame, type ChartLegendItem, type ChartMargins, type ChartValueFormat, CodeBlock, type CodeLineSpec, type ColorName, Column, Comparison, type ComparisonSideSpec, Connector, type CropMode, type CropRegion, DashedLine, DataTable, type DataflowBoundary, DataflowDiagram, type DataflowDiagramProps, type DataflowEdge, type DataflowEdgeMode, type DataflowNode, type DataflowNodeKind, type DataflowSchema, type DataflowSchemaDefinition, type DataflowSchemaField, type DefinedAnimation, type DeploymentBoundary, type DeploymentBoundaryKind, type DeploymentConnection, type DeploymentConnectionKind, DeploymentDiagram, type DeploymentDiagramProps, type DeploymentNode, type DeploymentNodeKind, type DeploymentPort, type DeploymentPortDirection, type DeploymentPortInput, DetailList, type DiagramIconDefinition, type DiagramIconRenderProps, DonutChart, type DonutChartSegment, DotPoint, EquationCard, Flow, FlowArrow, type FlowStageSpec, GradientChip, GraphDiagram, type GraphDiagramEdge, type GraphDiagramEdgeArrow, type GraphDiagramEdgeKind, type GraphDiagramEdgeStyle, type GraphDiagramGroup, type GraphDiagramNode, type GraphDiagramProps, Grid, type GridCell, Heatmap, Icon, type IconName, type IconProps, type IllustrationBuilder, type IntervalDatum, IntervalPlot, KeyValueList, type KeyValueRow, LayeredNetwork, type LayeredNetworkLayer, Legend, type LegendItem, LineChart, type LineChartSeries, MathText, Matrix, MetricCard, MiniBarChart, type MiniBarDatum, type OverflowResult, Panel, ParetoChart, type ParetoChartProps, type ParetoObjective, type ParetoXScale, Pipeline, type PipelineStage, type PlotArea, ProgressList, ProgressRow, type ProgressRowSpec, QuadrantChart, type QuadrantChartProps, type QuadrantRegion, type RenderBackground, type RenderOptions, type RenderOutput, Row, type SampleAnimationOptions, type SampledAnimationFrame, ScatterPlot, type ScatterPoint, Scene, type SequenceActivation, SequenceDiagram, type SequenceDiagramProps, type SequenceFragment, type SequenceFragmentBranch, type SequenceFragmentKind, type SequenceItem, type SequenceMessage, type SequenceMessageKind, type SequenceNote, type SequenceParticipant, type SequenceParticipantKind, Stack, StackedBar, type StackedBarSegment, type StatusKind, StatusList, StatusRow, type StatusRowSpec, StepCard, SvgFrame, SvgMathText, SvgPoint, type TensorDimension, type TensorShape, type TensorShapeObject, TextLabel, type ThemeColors, type ThemeMode, type ThemePreset, Tile, TileGrid, type TileSpec, TiledMatrix, type TiledMatrixRegion, Timeline, type TimelineEventSpec, TitleBar, type ToneName, ToneStrip, type TransformerBlock, type TransformerBlockKind, type TransformerRoute, type TransformerRouteKind, TransformerTopology, type TransformerTopologyProps, type TransitionType, TreeDiagram, type TreeNodeSpec, ValuePill, VectorArrow, VectorSegment, Watermark, type WatermarkElementProps, type WatermarkImageOptions, type WatermarkInput, type WatermarkOptions, type WatermarkPosition, WindowFrame, analyzeAnimationCadence, canvas, colors, createPlotArea, cropPixels, defineAnimation, defineDiagramIcon, defineIconRegistry, defineIllustration, detectBackgroundColor, detectContentBounds, detectOverflow, formatMathText, formatTensorShape, getColor, getFonts, getGradient, getReadableColor, getReadableTextColor, getReadableToneColor, getStyles, getThemeColors, getToneColor, getToneFill, getToneGradient, gradients, heatColor, hold, keyframe, loadAdditionalAsset, normalizeWatermark, parallel, renderAnimatedGif, renderAnimatedGifWithOutput, renderAnimationGif, renderAnimationGifWithOutput, renderToBuffer, renderToPng, renderToPngWithOutput, renderToSvg, sampleAnimation, sampleAnimationFrames, styles, toneGradients, tween, typography, wrapWithBrand, wrapWithWatermark };
2006
+ type GraphImportSource = 'mermaid' | 'd2';
2007
+ type GraphImportDirection = 'LR' | 'RL' | 'TB' | 'BT';
2008
+ type GraphImportDiagnosticCode = 'import.empty' | 'import.lossy_semantics' | 'import.parse_error' | 'import.unsupported_semantics' | 'import.unsupported_syntax';
2009
+ interface GraphImportDiagnostic {
2010
+ code: GraphImportDiagnosticCode;
2011
+ severity: 'error' | 'warning';
2012
+ message: string;
2013
+ line: number;
2014
+ column: number;
2015
+ excerpt: string;
2016
+ }
2017
+ interface GraphImportGraph {
2018
+ nodes: GraphDiagramNode[];
2019
+ edges: GraphDiagramEdge[];
2020
+ groups: GraphDiagramGroup[];
2021
+ direction: GraphImportDirection;
2022
+ }
2023
+ /**
2024
+ * A parse result is renderable only when `ok` is true and `graph` is present.
2025
+ * Warnings describe explicit, accepted losses; errors omit the graph so callers
2026
+ * cannot accidentally render a partial interpretation.
2027
+ */
2028
+ interface GraphImportResult {
2029
+ source: GraphImportSource;
2030
+ ok: boolean;
2031
+ graph?: GraphImportGraph;
2032
+ diagnostics: GraphImportDiagnostic[];
2033
+ }
2034
+
2035
+ /**
2036
+ * Import the conservative Mermaid flowchart subset documented in docs/import.md.
2037
+ * Unsupported constructs produce errors and suppress `graph`; accepted shape
2038
+ * reductions produce warnings that callers can show before rendering.
2039
+ */
2040
+ declare function importMermaidGraph(source: string): GraphImportResult;
2041
+
2042
+ /**
2043
+ * Import a safe subset of D2 text diagrams. The accepted syntax and explicit
2044
+ * reductions are documented in docs/import.md; unsupported blocks and fields
2045
+ * suppress `graph` rather than returning a partial diagram.
2046
+ */
2047
+ declare function importD2Graph(source: string): GraphImportResult;
2048
+
2049
+ type DiagnosticSeverity = 'error' | 'warning' | 'info';
2050
+ /** Stable identifiers emitted by the visual checker. Add codes without changing existing meanings. */
2051
+ declare const CHECK_DIAGNOSTIC_CODES: readonly ["accessibility.low_contrast", "api.unsupported_prop", "asset.warning", "frame.load_error", "frame.unknown_preset", "layout.auto_size", "layout.connector_congestion", "layout.overflow", "layout.text_overlap", "layout.whitespace_imbalance", "readability.small_text", "render.error", "render.warning", "style.unsupported"];
2052
+ type CheckDiagnosticCode = typeof CHECK_DIAGNOSTIC_CODES[number];
2053
+ interface CheckDiagnosticLocation {
2054
+ /** React element path for diagnostics collected before layout. */
2055
+ path?: string;
2056
+ /** Rendered logical-pixel bounds when layout data is available. */
2057
+ x?: number;
2058
+ y?: number;
2059
+ width?: number;
2060
+ height?: number;
2061
+ }
2062
+ interface CheckDiagnostic {
2063
+ code: CheckDiagnosticCode;
2064
+ severity: DiagnosticSeverity;
2065
+ message: string;
2066
+ theme?: ThemeMode;
2067
+ elementId?: string;
2068
+ relatedElementIds?: string[];
2069
+ location?: CheckDiagnosticLocation;
2070
+ edges?: Array<'top' | 'right' | 'bottom' | 'left'>;
2071
+ suggestion?: string;
2072
+ suggestedDimensions?: {
2073
+ width: number;
2074
+ height: number;
2075
+ };
2076
+ }
2077
+
2078
+ interface CheckAutoSizeAxes {
2079
+ width: boolean;
2080
+ height: boolean;
2081
+ }
2082
+ type CheckAutoSize = boolean | Partial<CheckAutoSizeAxes>;
2083
+ type CheckFrameShape = {
2084
+ source?: string;
2085
+ width?: number;
2086
+ height?: number;
2087
+ autoSize?: CheckAutoSize;
2088
+ };
2089
+ /** A frame can be a fixed React scene or a factory that creates a themed scene. */
2090
+ type CheckFrameInput = CheckFrameShape & ({
2091
+ scene: ReactNode;
2092
+ create?: never;
2093
+ } | {
2094
+ create: (theme: ThemeMode) => ReactNode;
2095
+ scene?: never;
2096
+ });
2097
+ type CheckFailurePolicy = DiagnosticSeverity | 'never';
2098
+ interface CheckOptions {
2099
+ /** Themes to check. Defaults to both Vizmatic themes. */
2100
+ themes?: readonly ThemeMode[];
2101
+ /** Background passed to Vizmatic primitives and the renderer. Defaults to transparent. */
2102
+ background?: RenderBackground;
2103
+ /** Minimum severity that makes the report fail. Defaults to errors only. */
2104
+ failOn?: CheckFailurePolicy;
2105
+ }
2106
+ interface CheckThemeReport {
2107
+ theme: ThemeMode;
2108
+ ok: boolean;
2109
+ dimensions: {
2110
+ input: {
2111
+ width: number;
2112
+ height: number;
2113
+ };
2114
+ resolved?: {
2115
+ width: number;
2116
+ height: number;
2117
+ };
2118
+ output?: {
2119
+ width: number;
2120
+ height: number;
2121
+ };
2122
+ };
2123
+ diagnostics: CheckDiagnostic[];
2124
+ }
2125
+ interface CheckDiagnosticCounts {
2126
+ errors: number;
2127
+ warnings: number;
2128
+ info: number;
2129
+ }
2130
+ interface CheckFrameReport {
2131
+ schemaVersion: 1;
2132
+ source?: string;
2133
+ ok: boolean;
2134
+ /** True when each requested theme completed rendering, regardless of failOn. */
2135
+ rendered: boolean;
2136
+ autoSize: CheckAutoSizeAxes;
2137
+ themes: CheckThemeReport[];
2138
+ summary: CheckDiagnosticCounts;
2139
+ }
2140
+ /**
2141
+ * Check a React scene or themed frame by rendering each requested theme and
2142
+ * returning structured diagnostics. This function does not write an artifact.
2143
+ */
2144
+ declare function checkFrame(input: CheckFrameInput, options?: CheckOptions): Promise<CheckFrameReport>;
2145
+
2146
+ export { type AnimatedScene, type AnimationCadenceAnalysis, type AnimationDefinition, type AnimationEasing, type AnimationEasingName, type AnimationFrameContext, type AnimationHoldStep, type AnimationInterpolator, type AnimationKeyframeStep, type AnimationOptions, type AnimationOutput, type AnimationOverflowContext, type AnimationParallelStep, type AnimationParallelTracks, type AnimationPropertyStep, type AnimationTimelineStep, type AnimationTweenStep, Arrow, ArrowMarkerDef, AxisPlot, type AxisPlotPath, type AxisPlotPoint, type AxisPlotVector, Badge, BadgePill, BarChart, type BarChartDatum, Box, CHECK_DIAGNOSTIC_CODES, CalloutCard, Canvas, CanvasOverflowError, Card, ChartFrame, type ChartLegendItem, type ChartMargins, type ChartValueFormat, type CheckAutoSize, type CheckAutoSizeAxes, type CheckDiagnostic, type CheckDiagnosticCode, type CheckDiagnosticCounts, type CheckDiagnosticLocation, type CheckFailurePolicy, type CheckFrameInput, type CheckFrameReport, type CheckOptions, type CheckThemeReport, CodeBlock, type CodeLineSpec, type ColorName, Column, Comparison, type ComparisonSideSpec, Connector, type CropMode, type CropRegion, DashedLine, DataTable, type DataflowBoundary, DataflowDiagram, type DataflowDiagramProps, type DataflowEdge, type DataflowEdgeMode, type DataflowNode, type DataflowNodeKind, type DataflowSchema, type DataflowSchemaDefinition, type DataflowSchemaField, type DefinedAnimation, type DeploymentBoundary, type DeploymentBoundaryKind, type DeploymentConnection, type DeploymentConnectionKind, DeploymentDiagram, type DeploymentDiagramProps, type DeploymentNode, type DeploymentNodeKind, type DeploymentPort, type DeploymentPortDirection, type DeploymentPortInput, DetailList, type DiagnosticSeverity, type DiagramIconDefinition, type DiagramIconRenderProps, DonutChart, type DonutChartSegment, DotPoint, EquationCard, Flow, FlowArrow, type FlowStageSpec, GradientChip, GraphDiagram, type GraphDiagramEdge, type GraphDiagramEdgeArrow, type GraphDiagramEdgeKind, type GraphDiagramEdgeStyle, type GraphDiagramGroup, type GraphDiagramNode, type GraphDiagramProps, type GraphImportDiagnostic, type GraphImportDiagnosticCode, type GraphImportDirection, type GraphImportGraph, type GraphImportResult, type GraphImportSource, Grid, type GridCell, Heatmap, Icon, type IconName, type IconProps, type IllustrationBuilder, type IntervalDatum, IntervalPlot, KeyValueList, type KeyValueRow, LayeredNetwork, type LayeredNetworkLayer, Legend, type LegendItem, LineChart, type LineChartSeries, MathText, Matrix, MetricCard, MiniBarChart, type MiniBarDatum, type OverflowResult, Panel, ParetoChart, type ParetoChartProps, type ParetoObjective, type ParetoXScale, Pipeline, type PipelineStage, type PlotArea, ProgressList, ProgressRow, type ProgressRowSpec, QuadrantChart, type QuadrantChartProps, type QuadrantRegion, type RenderBackground, type RenderOptions, type RenderOutput, Row, type SampleAnimationOptions, type SampledAnimationFrame, ScatterPlot, type ScatterPoint, Scene, type SequenceActivation, SequenceDiagram, type SequenceDiagramProps, type SequenceFragment, type SequenceFragmentBranch, type SequenceFragmentKind, type SequenceItem, type SequenceMessage, type SequenceMessageKind, type SequenceNote, type SequenceParticipant, type SequenceParticipantKind, Stack, StackedBar, type StackedBarSegment, type StatusKind, StatusList, StatusRow, type StatusRowSpec, StepCard, SvgFrame, SvgMathText, SvgPoint, type TensorDimension, type TensorShape, type TensorShapeObject, TextLabel, type ThemeColors, type ThemeMode, type ThemePreset, Tile, TileGrid, type TileSpec, TiledMatrix, type TiledMatrixRegion, Timeline, type TimelineEventSpec, TitleBar, type ToneName, ToneStrip, type TransformerBlock, type TransformerBlockKind, type TransformerRoute, type TransformerRouteKind, TransformerTopology, type TransformerTopologyProps, type TransitionType, TreeDiagram, type TreeNodeSpec, ValuePill, VectorArrow, VectorSegment, Watermark, type WatermarkElementProps, type WatermarkImageOptions, type WatermarkInput, type WatermarkOptions, type WatermarkPosition, WindowFrame, analyzeAnimationCadence, canvas, checkFrame, colors, createPlotArea, cropPixels, defineAnimation, defineDiagramIcon, defineIconRegistry, defineIllustration, detectBackgroundColor, detectContentBounds, detectOverflow, formatMathText, formatTensorShape, getColor, getFonts, getGradient, getReadableColor, getReadableTextColor, getReadableToneColor, getStyles, getThemeColors, getToneColor, getToneFill, getToneGradient, gradients, heatColor, hold, importD2Graph, importMermaidGraph, keyframe, loadAdditionalAsset, normalizeWatermark, parallel, renderAnimatedGif, renderAnimatedGifWithOutput, renderAnimationGif, renderAnimationGifWithOutput, renderToBuffer, renderToPng, renderToPngWithOutput, renderToSvg, sampleAnimation, sampleAnimationFrames, styles, toneGradients, tween, typography, wrapWithBrand, wrapWithWatermark };
package/dist/index.d.ts CHANGED
@@ -74,8 +74,8 @@ type ToneName = 'blue' | 'purple' | 'green' | 'warm' | 'cyan' | 'pink' | 'red' |
74
74
  declare const toneGradients: Record<ToneName, string>;
75
75
  declare function getToneGradient(tone: ToneName): string;
76
76
  declare function getToneColor(tone: ToneName, c: ThemeColors): string;
77
- /** Get a tone variant that remains readable as text in either theme. */
78
- declare function getReadableToneColor(tone: ToneName, c: ThemeColors, background?: string): string;
77
+ /** Get a tone variant that remains readable against the background over its backdrop. */
78
+ declare function getReadableToneColor(tone: ToneName, c: ThemeColors, background?: string, backdrop?: string): string;
79
79
  /** Low-chroma fills for diagrams. The engineering preset uses opaque pastels. */
80
80
  declare function getToneFill(tone: ToneName, c: ThemeColors): string;
81
81
  declare const typography: {
@@ -207,8 +207,8 @@ type ColorName = 'primary' | 'secondary' | 'positive' | 'warning' | 'critical' |
207
207
  declare function getColor(name: ColorName, c?: ThemeColors): string;
208
208
  /** Get a semantic color variant that remains readable as text in either theme. */
209
209
  declare function getReadableColor(name: ColorName, c: ThemeColors): string;
210
- /** Choose readable foreground text for a solid theme color. */
211
- declare function getReadableTextColor(background: string, c: ThemeColors): string;
210
+ /** Choose readable foreground text, compositing translucent backgrounds over their backdrop. */
211
+ declare function getReadableTextColor(background: string, c: ThemeColors, backdrop?: string): string;
212
212
  /**
213
213
  * Get a gradient by semantic name.
214
214
  * Gradients are the same for both themes (they sit on top of content
@@ -831,6 +831,8 @@ interface GraphDiagramNode {
831
831
  id: string;
832
832
  label: React.ReactNode;
833
833
  detail?: React.ReactNode;
834
+ href?: string;
835
+ title?: string;
834
836
  x?: number;
835
837
  y?: number;
836
838
  tone?: ToneName;
@@ -865,6 +867,7 @@ type GraphDiagramEdgeKind = 'sync' | 'async' | 'event' | 'data' | 'dependency' |
865
867
  type GraphDiagramEdgeStyle = 'solid' | 'dashed' | 'dotted';
866
868
  type GraphDiagramEdgeArrow = 'forward' | 'backward' | 'both' | 'none';
867
869
  interface GraphDiagramEdge {
870
+ id?: string;
868
871
  from: string;
869
872
  to: string;
870
873
  tone?: ToneName;
@@ -874,6 +877,8 @@ interface GraphDiagramEdge {
874
877
  kind?: GraphDiagramEdgeKind;
875
878
  style?: GraphDiagramEdgeStyle;
876
879
  arrow?: GraphDiagramEdgeArrow;
880
+ href?: string;
881
+ title?: string;
877
882
  }
878
883
  interface GraphDiagramProps {
879
884
  nodes: GraphDiagramNode[];
@@ -895,9 +900,12 @@ interface GraphDiagramProps {
895
900
  edgeGap?: number;
896
901
  sizing?: 'content' | 'fixed';
897
902
  iconSize?: number;
903
+ id?: string;
898
904
  ariaLabel?: string;
905
+ title?: string;
906
+ description?: string;
899
907
  }
900
- declare function GraphDiagram({ nodes, edges, groups, c, width, height, nodeWidth, nodeHeight, labelFontSize, detailFontSize, arrowSize, padding, layout: requestedLayout, direction, nodeGap, rankGap, edgeGap, sizing, iconSize, ariaLabel, }: GraphDiagramProps): React.ReactElement;
908
+ declare function GraphDiagram({ nodes, edges, groups, c, width, height, nodeWidth, nodeHeight, labelFontSize, detailFontSize, arrowSize, padding, layout: requestedLayout, direction, nodeGap, rankGap, edgeGap, sizing, iconSize, id, ariaLabel, title, description, }: GraphDiagramProps): React.ReactElement;
901
909
  interface TreeNodeSpec {
902
910
  label: React.ReactNode;
903
911
  id?: string;
@@ -1055,6 +1063,8 @@ interface DataflowNode {
1055
1063
  id: string;
1056
1064
  label: React.ReactNode;
1057
1065
  detail?: React.ReactNode;
1066
+ href?: string;
1067
+ title?: string;
1058
1068
  kind: DataflowNodeKind;
1059
1069
  schema?: DataflowSchema;
1060
1070
  tone?: ToneName;
@@ -1065,9 +1075,12 @@ interface DataflowNode {
1065
1075
  height?: number;
1066
1076
  }
1067
1077
  interface DataflowEdge {
1078
+ id?: string;
1068
1079
  from: string;
1069
1080
  to: string;
1070
1081
  label?: string;
1082
+ href?: string;
1083
+ title?: string;
1071
1084
  schema?: DataflowSchema;
1072
1085
  mode?: DataflowEdgeMode;
1073
1086
  tone?: ToneName;
@@ -1086,6 +1099,9 @@ interface DataflowSpec {
1086
1099
  edges: DataflowEdge[];
1087
1100
  boundaries?: DataflowBoundary[];
1088
1101
  ariaLabel?: string;
1102
+ id?: string;
1103
+ title?: string;
1104
+ description?: string;
1089
1105
  }
1090
1106
  interface DataflowDiagramProps extends DataflowSpec {
1091
1107
  c: ThemeColors;
@@ -1105,7 +1121,7 @@ interface DataflowDiagramProps extends DataflowSpec {
1105
1121
  iconSize?: number;
1106
1122
  }
1107
1123
  /** Render typed dataflow nodes and edges through the existing GraphDiagram. */
1108
- declare function DataflowDiagram({ c, nodes, edges, boundaries, ariaLabel, width, height, nodeWidth, nodeHeight, labelFontSize, detailFontSize, arrowSize, padding, direction, nodeGap, rankGap, edgeGap, sizing, iconSize, }: DataflowDiagramProps): React.ReactElement;
1124
+ declare function DataflowDiagram({ c, nodes, edges, boundaries, ariaLabel, id, title, description, width, height, nodeWidth, nodeHeight, labelFontSize, detailFontSize, arrowSize, padding, direction, nodeGap, rankGap, edgeGap, sizing, iconSize, }: DataflowDiagramProps): React.ReactElement;
1109
1125
 
1110
1126
  /** Deployment boundary kinds understood by {@link DeploymentDiagram}. */
1111
1127
  type DeploymentBoundaryKind = 'region' | 'zone' | 'vpc' | 'subnet' | 'namespace' | 'host' | 'cluster' | 'trust';
@@ -1987,4 +2003,144 @@ declare function renderAnimatedGifWithOutput(scenes: AnimatedScene[], options: A
1987
2003
  declare function renderAnimationGif<S extends object>(animation: DefinedAnimation<S>, options: AnimationOptions): Promise<void>;
1988
2004
  declare function renderAnimationGifWithOutput<S extends object>(animation: DefinedAnimation<S>, options: AnimationOptions): Promise<AnimationOutput>;
1989
2005
 
1990
- export { type AnimatedScene, type AnimationCadenceAnalysis, type AnimationDefinition, type AnimationEasing, type AnimationEasingName, type AnimationFrameContext, type AnimationHoldStep, type AnimationInterpolator, type AnimationKeyframeStep, type AnimationOptions, type AnimationOutput, type AnimationOverflowContext, type AnimationParallelStep, type AnimationParallelTracks, type AnimationPropertyStep, type AnimationTimelineStep, type AnimationTweenStep, Arrow, ArrowMarkerDef, AxisPlot, type AxisPlotPath, type AxisPlotPoint, type AxisPlotVector, Badge, BadgePill, BarChart, type BarChartDatum, Box, CalloutCard, Canvas, CanvasOverflowError, Card, ChartFrame, type ChartLegendItem, type ChartMargins, type ChartValueFormat, CodeBlock, type CodeLineSpec, type ColorName, Column, Comparison, type ComparisonSideSpec, Connector, type CropMode, type CropRegion, DashedLine, DataTable, type DataflowBoundary, DataflowDiagram, type DataflowDiagramProps, type DataflowEdge, type DataflowEdgeMode, type DataflowNode, type DataflowNodeKind, type DataflowSchema, type DataflowSchemaDefinition, type DataflowSchemaField, type DefinedAnimation, type DeploymentBoundary, type DeploymentBoundaryKind, type DeploymentConnection, type DeploymentConnectionKind, DeploymentDiagram, type DeploymentDiagramProps, type DeploymentNode, type DeploymentNodeKind, type DeploymentPort, type DeploymentPortDirection, type DeploymentPortInput, DetailList, type DiagramIconDefinition, type DiagramIconRenderProps, DonutChart, type DonutChartSegment, DotPoint, EquationCard, Flow, FlowArrow, type FlowStageSpec, GradientChip, GraphDiagram, type GraphDiagramEdge, type GraphDiagramEdgeArrow, type GraphDiagramEdgeKind, type GraphDiagramEdgeStyle, type GraphDiagramGroup, type GraphDiagramNode, type GraphDiagramProps, Grid, type GridCell, Heatmap, Icon, type IconName, type IconProps, type IllustrationBuilder, type IntervalDatum, IntervalPlot, KeyValueList, type KeyValueRow, LayeredNetwork, type LayeredNetworkLayer, Legend, type LegendItem, LineChart, type LineChartSeries, MathText, Matrix, MetricCard, MiniBarChart, type MiniBarDatum, type OverflowResult, Panel, ParetoChart, type ParetoChartProps, type ParetoObjective, type ParetoXScale, Pipeline, type PipelineStage, type PlotArea, ProgressList, ProgressRow, type ProgressRowSpec, QuadrantChart, type QuadrantChartProps, type QuadrantRegion, type RenderBackground, type RenderOptions, type RenderOutput, Row, type SampleAnimationOptions, type SampledAnimationFrame, ScatterPlot, type ScatterPoint, Scene, type SequenceActivation, SequenceDiagram, type SequenceDiagramProps, type SequenceFragment, type SequenceFragmentBranch, type SequenceFragmentKind, type SequenceItem, type SequenceMessage, type SequenceMessageKind, type SequenceNote, type SequenceParticipant, type SequenceParticipantKind, Stack, StackedBar, type StackedBarSegment, type StatusKind, StatusList, StatusRow, type StatusRowSpec, StepCard, SvgFrame, SvgMathText, SvgPoint, type TensorDimension, type TensorShape, type TensorShapeObject, TextLabel, type ThemeColors, type ThemeMode, type ThemePreset, Tile, TileGrid, type TileSpec, TiledMatrix, type TiledMatrixRegion, Timeline, type TimelineEventSpec, TitleBar, type ToneName, ToneStrip, type TransformerBlock, type TransformerBlockKind, type TransformerRoute, type TransformerRouteKind, TransformerTopology, type TransformerTopologyProps, type TransitionType, TreeDiagram, type TreeNodeSpec, ValuePill, VectorArrow, VectorSegment, Watermark, type WatermarkElementProps, type WatermarkImageOptions, type WatermarkInput, type WatermarkOptions, type WatermarkPosition, WindowFrame, analyzeAnimationCadence, canvas, colors, createPlotArea, cropPixels, defineAnimation, defineDiagramIcon, defineIconRegistry, defineIllustration, detectBackgroundColor, detectContentBounds, detectOverflow, formatMathText, formatTensorShape, getColor, getFonts, getGradient, getReadableColor, getReadableTextColor, getReadableToneColor, getStyles, getThemeColors, getToneColor, getToneFill, getToneGradient, gradients, heatColor, hold, keyframe, loadAdditionalAsset, normalizeWatermark, parallel, renderAnimatedGif, renderAnimatedGifWithOutput, renderAnimationGif, renderAnimationGifWithOutput, renderToBuffer, renderToPng, renderToPngWithOutput, renderToSvg, sampleAnimation, sampleAnimationFrames, styles, toneGradients, tween, typography, wrapWithBrand, wrapWithWatermark };
2006
+ type GraphImportSource = 'mermaid' | 'd2';
2007
+ type GraphImportDirection = 'LR' | 'RL' | 'TB' | 'BT';
2008
+ type GraphImportDiagnosticCode = 'import.empty' | 'import.lossy_semantics' | 'import.parse_error' | 'import.unsupported_semantics' | 'import.unsupported_syntax';
2009
+ interface GraphImportDiagnostic {
2010
+ code: GraphImportDiagnosticCode;
2011
+ severity: 'error' | 'warning';
2012
+ message: string;
2013
+ line: number;
2014
+ column: number;
2015
+ excerpt: string;
2016
+ }
2017
+ interface GraphImportGraph {
2018
+ nodes: GraphDiagramNode[];
2019
+ edges: GraphDiagramEdge[];
2020
+ groups: GraphDiagramGroup[];
2021
+ direction: GraphImportDirection;
2022
+ }
2023
+ /**
2024
+ * A parse result is renderable only when `ok` is true and `graph` is present.
2025
+ * Warnings describe explicit, accepted losses; errors omit the graph so callers
2026
+ * cannot accidentally render a partial interpretation.
2027
+ */
2028
+ interface GraphImportResult {
2029
+ source: GraphImportSource;
2030
+ ok: boolean;
2031
+ graph?: GraphImportGraph;
2032
+ diagnostics: GraphImportDiagnostic[];
2033
+ }
2034
+
2035
+ /**
2036
+ * Import the conservative Mermaid flowchart subset documented in docs/import.md.
2037
+ * Unsupported constructs produce errors and suppress `graph`; accepted shape
2038
+ * reductions produce warnings that callers can show before rendering.
2039
+ */
2040
+ declare function importMermaidGraph(source: string): GraphImportResult;
2041
+
2042
+ /**
2043
+ * Import a safe subset of D2 text diagrams. The accepted syntax and explicit
2044
+ * reductions are documented in docs/import.md; unsupported blocks and fields
2045
+ * suppress `graph` rather than returning a partial diagram.
2046
+ */
2047
+ declare function importD2Graph(source: string): GraphImportResult;
2048
+
2049
+ type DiagnosticSeverity = 'error' | 'warning' | 'info';
2050
+ /** Stable identifiers emitted by the visual checker. Add codes without changing existing meanings. */
2051
+ declare const CHECK_DIAGNOSTIC_CODES: readonly ["accessibility.low_contrast", "api.unsupported_prop", "asset.warning", "frame.load_error", "frame.unknown_preset", "layout.auto_size", "layout.connector_congestion", "layout.overflow", "layout.text_overlap", "layout.whitespace_imbalance", "readability.small_text", "render.error", "render.warning", "style.unsupported"];
2052
+ type CheckDiagnosticCode = typeof CHECK_DIAGNOSTIC_CODES[number];
2053
+ interface CheckDiagnosticLocation {
2054
+ /** React element path for diagnostics collected before layout. */
2055
+ path?: string;
2056
+ /** Rendered logical-pixel bounds when layout data is available. */
2057
+ x?: number;
2058
+ y?: number;
2059
+ width?: number;
2060
+ height?: number;
2061
+ }
2062
+ interface CheckDiagnostic {
2063
+ code: CheckDiagnosticCode;
2064
+ severity: DiagnosticSeverity;
2065
+ message: string;
2066
+ theme?: ThemeMode;
2067
+ elementId?: string;
2068
+ relatedElementIds?: string[];
2069
+ location?: CheckDiagnosticLocation;
2070
+ edges?: Array<'top' | 'right' | 'bottom' | 'left'>;
2071
+ suggestion?: string;
2072
+ suggestedDimensions?: {
2073
+ width: number;
2074
+ height: number;
2075
+ };
2076
+ }
2077
+
2078
+ interface CheckAutoSizeAxes {
2079
+ width: boolean;
2080
+ height: boolean;
2081
+ }
2082
+ type CheckAutoSize = boolean | Partial<CheckAutoSizeAxes>;
2083
+ type CheckFrameShape = {
2084
+ source?: string;
2085
+ width?: number;
2086
+ height?: number;
2087
+ autoSize?: CheckAutoSize;
2088
+ };
2089
+ /** A frame can be a fixed React scene or a factory that creates a themed scene. */
2090
+ type CheckFrameInput = CheckFrameShape & ({
2091
+ scene: ReactNode;
2092
+ create?: never;
2093
+ } | {
2094
+ create: (theme: ThemeMode) => ReactNode;
2095
+ scene?: never;
2096
+ });
2097
+ type CheckFailurePolicy = DiagnosticSeverity | 'never';
2098
+ interface CheckOptions {
2099
+ /** Themes to check. Defaults to both Vizmatic themes. */
2100
+ themes?: readonly ThemeMode[];
2101
+ /** Background passed to Vizmatic primitives and the renderer. Defaults to transparent. */
2102
+ background?: RenderBackground;
2103
+ /** Minimum severity that makes the report fail. Defaults to errors only. */
2104
+ failOn?: CheckFailurePolicy;
2105
+ }
2106
+ interface CheckThemeReport {
2107
+ theme: ThemeMode;
2108
+ ok: boolean;
2109
+ dimensions: {
2110
+ input: {
2111
+ width: number;
2112
+ height: number;
2113
+ };
2114
+ resolved?: {
2115
+ width: number;
2116
+ height: number;
2117
+ };
2118
+ output?: {
2119
+ width: number;
2120
+ height: number;
2121
+ };
2122
+ };
2123
+ diagnostics: CheckDiagnostic[];
2124
+ }
2125
+ interface CheckDiagnosticCounts {
2126
+ errors: number;
2127
+ warnings: number;
2128
+ info: number;
2129
+ }
2130
+ interface CheckFrameReport {
2131
+ schemaVersion: 1;
2132
+ source?: string;
2133
+ ok: boolean;
2134
+ /** True when each requested theme completed rendering, regardless of failOn. */
2135
+ rendered: boolean;
2136
+ autoSize: CheckAutoSizeAxes;
2137
+ themes: CheckThemeReport[];
2138
+ summary: CheckDiagnosticCounts;
2139
+ }
2140
+ /**
2141
+ * Check a React scene or themed frame by rendering each requested theme and
2142
+ * returning structured diagnostics. This function does not write an artifact.
2143
+ */
2144
+ declare function checkFrame(input: CheckFrameInput, options?: CheckOptions): Promise<CheckFrameReport>;
2145
+
2146
+ export { type AnimatedScene, type AnimationCadenceAnalysis, type AnimationDefinition, type AnimationEasing, type AnimationEasingName, type AnimationFrameContext, type AnimationHoldStep, type AnimationInterpolator, type AnimationKeyframeStep, type AnimationOptions, type AnimationOutput, type AnimationOverflowContext, type AnimationParallelStep, type AnimationParallelTracks, type AnimationPropertyStep, type AnimationTimelineStep, type AnimationTweenStep, Arrow, ArrowMarkerDef, AxisPlot, type AxisPlotPath, type AxisPlotPoint, type AxisPlotVector, Badge, BadgePill, BarChart, type BarChartDatum, Box, CHECK_DIAGNOSTIC_CODES, CalloutCard, Canvas, CanvasOverflowError, Card, ChartFrame, type ChartLegendItem, type ChartMargins, type ChartValueFormat, type CheckAutoSize, type CheckAutoSizeAxes, type CheckDiagnostic, type CheckDiagnosticCode, type CheckDiagnosticCounts, type CheckDiagnosticLocation, type CheckFailurePolicy, type CheckFrameInput, type CheckFrameReport, type CheckOptions, type CheckThemeReport, CodeBlock, type CodeLineSpec, type ColorName, Column, Comparison, type ComparisonSideSpec, Connector, type CropMode, type CropRegion, DashedLine, DataTable, type DataflowBoundary, DataflowDiagram, type DataflowDiagramProps, type DataflowEdge, type DataflowEdgeMode, type DataflowNode, type DataflowNodeKind, type DataflowSchema, type DataflowSchemaDefinition, type DataflowSchemaField, type DefinedAnimation, type DeploymentBoundary, type DeploymentBoundaryKind, type DeploymentConnection, type DeploymentConnectionKind, DeploymentDiagram, type DeploymentDiagramProps, type DeploymentNode, type DeploymentNodeKind, type DeploymentPort, type DeploymentPortDirection, type DeploymentPortInput, DetailList, type DiagnosticSeverity, type DiagramIconDefinition, type DiagramIconRenderProps, DonutChart, type DonutChartSegment, DotPoint, EquationCard, Flow, FlowArrow, type FlowStageSpec, GradientChip, GraphDiagram, type GraphDiagramEdge, type GraphDiagramEdgeArrow, type GraphDiagramEdgeKind, type GraphDiagramEdgeStyle, type GraphDiagramGroup, type GraphDiagramNode, type GraphDiagramProps, type GraphImportDiagnostic, type GraphImportDiagnosticCode, type GraphImportDirection, type GraphImportGraph, type GraphImportResult, type GraphImportSource, Grid, type GridCell, Heatmap, Icon, type IconName, type IconProps, type IllustrationBuilder, type IntervalDatum, IntervalPlot, KeyValueList, type KeyValueRow, LayeredNetwork, type LayeredNetworkLayer, Legend, type LegendItem, LineChart, type LineChartSeries, MathText, Matrix, MetricCard, MiniBarChart, type MiniBarDatum, type OverflowResult, Panel, ParetoChart, type ParetoChartProps, type ParetoObjective, type ParetoXScale, Pipeline, type PipelineStage, type PlotArea, ProgressList, ProgressRow, type ProgressRowSpec, QuadrantChart, type QuadrantChartProps, type QuadrantRegion, type RenderBackground, type RenderOptions, type RenderOutput, Row, type SampleAnimationOptions, type SampledAnimationFrame, ScatterPlot, type ScatterPoint, Scene, type SequenceActivation, SequenceDiagram, type SequenceDiagramProps, type SequenceFragment, type SequenceFragmentBranch, type SequenceFragmentKind, type SequenceItem, type SequenceMessage, type SequenceMessageKind, type SequenceNote, type SequenceParticipant, type SequenceParticipantKind, Stack, StackedBar, type StackedBarSegment, type StatusKind, StatusList, StatusRow, type StatusRowSpec, StepCard, SvgFrame, SvgMathText, SvgPoint, type TensorDimension, type TensorShape, type TensorShapeObject, TextLabel, type ThemeColors, type ThemeMode, type ThemePreset, Tile, TileGrid, type TileSpec, TiledMatrix, type TiledMatrixRegion, Timeline, type TimelineEventSpec, TitleBar, type ToneName, ToneStrip, type TransformerBlock, type TransformerBlockKind, type TransformerRoute, type TransformerRouteKind, TransformerTopology, type TransformerTopologyProps, type TransitionType, TreeDiagram, type TreeNodeSpec, ValuePill, VectorArrow, VectorSegment, Watermark, type WatermarkElementProps, type WatermarkImageOptions, type WatermarkInput, type WatermarkOptions, type WatermarkPosition, WindowFrame, analyzeAnimationCadence, canvas, checkFrame, colors, createPlotArea, cropPixels, defineAnimation, defineDiagramIcon, defineIconRegistry, defineIllustration, detectBackgroundColor, detectContentBounds, detectOverflow, formatMathText, formatTensorShape, getColor, getFonts, getGradient, getReadableColor, getReadableTextColor, getReadableToneColor, getStyles, getThemeColors, getToneColor, getToneFill, getToneGradient, gradients, heatColor, hold, importD2Graph, importMermaidGraph, keyframe, loadAdditionalAsset, normalizeWatermark, parallel, renderAnimatedGif, renderAnimatedGifWithOutput, renderAnimationGif, renderAnimationGifWithOutput, renderToBuffer, renderToPng, renderToPngWithOutput, renderToSvg, sampleAnimation, sampleAnimationFrames, styles, toneGradients, tween, typography, wrapWithBrand, wrapWithWatermark };