Add UI positioning strategy and placement options

Introduces the Placement enum to geometry.h for specifying UI element placement relative to anchors, with detailed documentation. Adds PositioningStrategy class and implementation to support absolute, cursor-based, and rectangle-relative positioning for UI elements.

Author: lijy91

src/foundation/geometry.h

@@ -28,4 +28,99 @@ struct Rectangle {
   double height;
 };
 
+/**
+ * @brief Placement options for positioning UI elements relative to an anchor.
+ *
+ * Defines how a UI element (such as a menu, tooltip, or popover) should be
+ * positioned relative to an anchor element or point. The placement consists
+ * of a primary direction (top, right, bottom, left) and an optional alignment
+ * (start, center, end).
+ *
+ * Primary directions:
+ * - Top: Element appears above the anchor
+ * - Right: Element appears to the right of the anchor
+ * - Bottom: Element appears below the anchor
+ * - Left: Element appears to the left of the anchor
+ *
+ * Alignments:
+ * - Start: Element aligns to the start edge (left for horizontal, top for vertical)
+ * - Center: Element centers along the anchor (default if not specified)
+ * - End: Element aligns to the end edge (right for horizontal, bottom for vertical)
+ *
+ * @note Use with PositioningStrategy (defined in positioning_strategy.h) to
+ *       specify both where and how to position UI elements.
+ *
+ * @example
+ * ```cpp
+ * // Position menu below the button, aligned to the left
+ * menu->Open(PositioningStrategy::Absolute(100, 100), Placement::BottomStart);
+ *
+ * // Position popover to the right, aligned to the top
+ * popover->Open(PositioningStrategy::CursorPosition(), Placement::RightStart);
+ * ```
+ *
+ * @see PositioningStrategy
+ */
+enum class Placement {
+  /**
+   * Position above the anchor, horizontally centered.
+   */
+  Top,
+
+  /**
+   * Position above the anchor, aligned to the start (left).
+   */
+  TopStart,
+
+  /**
+   * Position above the anchor, aligned to the end (right).
+   */
+  TopEnd,
+
+  /**
+   * Position to the right of the anchor, vertically centered.
+   */
+  Right,
+
+  /**
+   * Position to the right of the anchor, aligned to the start (top).
+   */
+  RightStart,
+
+  /**
+   * Position to the right of the anchor, aligned to the end (bottom).
+   */
+  RightEnd,
+
+  /**
+   * Position below the anchor, horizontally centered.
+   */
+  Bottom,
+
+  /**
+   * Position below the anchor, aligned to the start (left).
+   */
+  BottomStart,
+
+  /**
+   * Position below the anchor, aligned to the end (right).
+   */
+  BottomEnd,
+
+  /**
+   * Position to the left of the anchor, vertically centered.
+   */
+  Left,
+
+  /**
+   * Position to the left of the anchor, aligned to the start (top).
+   */
+  LeftStart,
+
+  /**
+   * Position to the left of the anchor, aligned to the end (bottom).
+   */
+  LeftEnd
+};
+
 }  // namespace nativeapi

src/foundation/positioning_strategy.cpp

@@ -0,0 +1,26 @@
+#include "positioning_strategy.h"
+
+namespace nativeapi {
+
+PositioningStrategy::PositioningStrategy(Type type)
+    : type_(type), absolute_position_{0, 0}, relative_rect_{0, 0, 0, 0}, relative_offset_{0, 0} {}
+
+PositioningStrategy PositioningStrategy::Absolute(double x, double y) {
+  PositioningStrategy strategy(Type::Absolute);
+  strategy.absolute_position_ = {x, y};
+  return strategy;
+}
+
+PositioningStrategy PositioningStrategy::CursorPosition() {
+  return PositioningStrategy(Type::CursorPosition);
+}
+
+PositioningStrategy PositioningStrategy::Relative(const Rectangle& rect, const Point& offset) {
+  PositioningStrategy strategy(Type::Relative);
+  strategy.relative_rect_ = rect;
+  strategy.relative_offset_ = offset;
+  return strategy;
+}
+
+}  // namespace nativeapi
+

src/foundation/positioning_strategy.h

@@ -0,0 +1,142 @@
+#pragma once
+#include "geometry.h"
+
+namespace nativeapi {
+
+/**
+ * @brief Strategy for determining where to position UI elements.
+ *
+ * PositioningStrategy defines how to calculate the position for UI elements
+ * such as menus, tooltips, or popovers. It supports various positioning modes:
+ * - Absolute: Fixed screen coordinates
+ * - CursorPosition: Current mouse cursor position
+ * - Relative: Position relative to a rectangle
+ *
+ * @example
+ * ```cpp
+ * // Position menu at absolute screen coordinates
+ * menu->Open(PositioningStrategy::Absolute(100, 200), Placement::Bottom);
+ *
+ * // Position menu at current mouse location
+ * menu->Open(PositioningStrategy::CursorPosition(), Placement::BottomStart);
+ *
+ * // Position menu relative to a rectangle
+ * Rectangle buttonRect = button->GetBounds();
+ * menu->Open(PositioningStrategy::Relative(buttonRect, {0, 10}), Placement::Bottom);
+ * ```
+ */
+class PositioningStrategy {
+ public:
+  /**
+   * @brief Type of positioning strategy.
+   */
+  enum class Type {
+    /**
+     * Position at fixed screen coordinates.
+     */
+    Absolute,
+
+    /**
+     * Position at current mouse cursor location.
+     */
+    CursorPosition,
+
+    /**
+     * Position relative to a rectangle.
+     */
+    Relative
+  };
+
+  /**
+   * @brief Create a strategy for absolute positioning at fixed coordinates.
+   *
+   * @param x X-coordinate in screen space
+   * @param y Y-coordinate in screen space
+   * @return PositioningStrategy configured for absolute positioning
+   *
+   * @example
+   * ```cpp
+   * auto strategy = PositioningStrategy::Absolute(100, 200);
+   * menu->Open(strategy, Placement::Bottom);
+   * ```
+   */
+  static PositioningStrategy Absolute(double x, double y);
+
+  /**
+   * @brief Create a strategy for positioning at current mouse location.
+   *
+   * @return PositioningStrategy configured to use mouse cursor position
+   *
+   * @example
+   * ```cpp
+   * auto strategy = PositioningStrategy::CursorPosition();
+   * contextMenu->Open(strategy, Placement::BottomStart);
+   * ```
+   */
+  static PositioningStrategy CursorPosition();
+
+  /**
+   * @brief Create a strategy for positioning relative to a rectangle.
+   *
+   * @param rect Rectangle in screen coordinates to position relative to
+   * @param offset Optional offset point to apply to the position (default: {0, 0})
+   * @return PositioningStrategy configured for rectangle-relative positioning
+   *
+   * @example
+   * ```cpp
+   * Rectangle buttonRect = button->GetBounds();
+   * // Position at bottom of button
+   * auto strategy = PositioningStrategy::Relative(buttonRect);
+   * menu->Open(strategy, Placement::Bottom);
+   *
+   * // Position at bottom of button with 10px offset
+   * auto strategy2 = PositioningStrategy::Relative(buttonRect, {0, 10});
+   * menu->Open(strategy2, Placement::Bottom);
+   * ```
+   */
+  static PositioningStrategy Relative(const Rectangle& rect, const Point& offset = {0, 0});
+
+  /**
+   * @brief Get the type of this positioning strategy.
+   *
+   * @return The Type enum value indicating the strategy type
+   */
+  Type GetType() const { return type_; }
+
+  /**
+   * @brief Get the absolute position (for Absolute type).
+   *
+   * @return Point containing x,y coordinates
+   * @note Only valid when GetType() == Type::Absolute
+   */
+  Point GetAbsolutePosition() const { return absolute_position_; }
+
+  /**
+   * @brief Get the relative rectangle (for Relative type).
+   *
+   * @return Rectangle in screen coordinates
+   * @note Only valid when GetType() == Type::Relative
+   */
+  Rectangle GetRelativeRectangle() const { return relative_rect_; }
+
+  /**
+   * @brief Get the relative offset point (for Relative type).
+   *
+   * @return Point containing x,y relative offset
+   * @note Only valid when GetType() == Type::Relative
+   */
+  Point GetRelativeOffset() const { return relative_offset_; }
+
+ private:
+  /**
+   * @brief Private constructor - use static factory methods instead.
+   */
+  PositioningStrategy(Type type);
+
+  Type type_;
+  Point absolute_position_;
+  Rectangle relative_rect_;
+  Point relative_offset_;
+};
+
+}  // namespace nativeapi