Add built-in bordered portal rendering and point-anchored positioning

Author: nickprotop

SharpConsoleUI/Controls/PortalContentBase.cs

@@ -7,6 +7,7 @@
 // -----------------------------------------------------------------------
 
 using System.Drawing;
+using SharpConsoleUI.Drawing;
 using SharpConsoleUI.Events;
 using SharpConsoleUI.Layout;
 using Color = Spectre.Console.Color;
@@ -27,6 +28,19 @@ public abstract class PortalContentBase : IWindowControl, IDOMPaintable, IMouseA
 		private int _actualWidth;
 		private int _actualHeight;
 
+		/// <summary>
+		/// When set, PaintDOM draws a border using these characters and shrinks the
+		/// inner bounds by 1 on each side before calling <see cref="PaintPortalContent"/>.
+		/// Mouse coordinates are automatically adjusted by (-1,-1) for the border offset.
+		/// </summary>
+		public BoxChars? BorderStyle { get; set; }
+
+		/// <summary>Foreground color for the border characters. Falls back to the default foreground.</summary>
+		public Color? BorderColor { get; set; }
+
+		/// <summary>Background color for the border and fill area. Falls back to the default background.</summary>
+		public Color? BorderBackgroundColor { get; set; }
+
 		#region IHasPortalBounds
 
 		/// <summary>
@@ -79,7 +93,25 @@ public abstract class PortalContentBase : IWindowControl, IDOMPaintable, IMouseA
 		public event EventHandler<MouseEventArgs>? MouseMove;
 		#pragma warning restore CS0067
 
-		/// <inheritdoc/>
+		/// <summary>
+		/// Explicit interface implementation that adjusts mouse coordinates for the border
+		/// offset before delegating to the public virtual <see cref="ProcessMouseEvent"/>.
+		/// </summary>
+		bool IMouseAwareControl.ProcessMouseEvent(MouseEventArgs args)
+		{
+			if (BorderStyle.HasValue)
+			{
+				var adjusted = args.WithPosition(
+					new System.Drawing.Point(args.Position.X - 1, args.Position.Y - 1));
+				return ProcessMouseEvent(adjusted);
+			}
+			return ProcessMouseEvent(args);
+		}
+
+		/// <summary>
+		/// Processes a mouse event. When <see cref="BorderStyle"/> is set, coordinates
+		/// are already adjusted for the border offset.
+		/// </summary>
 		public abstract bool ProcessMouseEvent(MouseEventArgs args);
 
 		#endregion
@@ -167,7 +199,18 @@ public void PaintDOM(CharacterBuffer buffer, LayoutRect bounds, LayoutRect clipR
 			_actualWidth = bounds.Width;
 			_actualHeight = bounds.Height;
 
-			PaintPortalContent(buffer, bounds, clipRect, defaultFg, defaultBg);
+			if (BorderStyle is { } border)
+			{
+				buffer.DrawBox(bounds, border, BorderColor ?? defaultFg,
+					BorderBackgroundColor ?? defaultBg);
+				var inner = new LayoutRect(bounds.X + 1, bounds.Y + 1,
+					Math.Max(0, bounds.Width - 2), Math.Max(0, bounds.Height - 2));
+				PaintPortalContent(buffer, inner, clipRect, defaultFg, defaultBg);
+			}
+			else
+			{
+				PaintPortalContent(buffer, bounds, clipRect, defaultFg, defaultBg);
+			}
 		}
 
 		/// <summary>

SharpConsoleUI/Layout/PortalPositioner.cs

@@ -160,6 +160,38 @@ public static PortalPositionResult Calculate(PortalPositionRequest request)
 			);
 		}
 
+		/// <summary>
+		/// Calculates the optimal position for a portal anchored at a single point
+		/// (e.g. a cursor position) rather than a rectangle.
+		/// </summary>
+		/// <param name="anchor">The point anchor (e.g. cursor position).</param>
+		/// <param name="contentSize">The desired size of the portal content.</param>
+		/// <param name="screenBounds">The available screen/window area to position within.</param>
+		/// <param name="placement">Preferred placement direction (default: BelowOrAbove).</param>
+		/// <param name="minSize">Minimum dimensions to enforce on the result.</param>
+		/// <returns>The calculated position result.</returns>
+		public static PortalPositionResult CalculateFromPoint(
+			Point anchor, Size contentSize, Rectangle screenBounds,
+			PortalPlacement placement = PortalPlacement.BelowOrAbove,
+			Size minSize = default)
+		{
+			// Point anchor → zero-width, 1-height rect (cursor occupies 1 row)
+			var anchorRect = new Rectangle(anchor.X, anchor.Y, 0, 1);
+			var result = Calculate(new PortalPositionRequest(anchorRect, contentSize, screenBounds, placement));
+
+			// Enforce minimum dimensions
+			if (minSize.Width > 0 || minSize.Height > 0)
+			{
+				var b = result.Bounds;
+				int w = Math.Max(b.Width, minSize.Width);
+				int h = Math.Max(b.Height, minSize.Height);
+				if (w != b.Width || h != b.Height)
+					return new PortalPositionResult(
+						new Rectangle(b.X, b.Y, w, h), result.ActualPlacement, result.WasClamped);
+			}
+			return result;
+		}
+
 		/// <summary>
 		/// Resolves a composite placement (e.g. BelowOrAbove) into a concrete direction
 		/// based on available space.