Expose Framework Laptop 16 input module physical position

Introduce `FrameworkInputModulePosition` enum to describe the physical
slot of input-deck modules on the Framework Laptop 16. This position
information is now included in `FrameworkModuleDescriptorSnapshot`,
providing more granular context for module identification and placement.

Author: TekuSP

framework-dotnet/Enums/FrameworkInputModulePosition.cs

@@ -0,0 +1,33 @@
+namespace FrameworkDotnet.Enums;
+
+/// <summary>
+/// Represents the physical position of an input-deck module on Framework Laptop 16 (the 8-wide input-deck MUX).
+/// Mirrors the native input-deck slots; <see cref="Unknown"/> for any module that is not input-deck-mounted or on
+/// platforms that do not report a deck position.
+/// </summary>
+public enum FrameworkInputModulePosition : ushort
+{
+    /// <summary>Not an input-deck-mounted module, or the platform reports no deck position.</summary>
+    Unknown = 0,
+
+    /// <summary>Top-row slot 0 (far left).</summary>
+    TopRow0 = 1,
+
+    /// <summary>Top-row slot 1.</summary>
+    TopRow1 = 2,
+
+    /// <summary>Top-row slot 2.</summary>
+    TopRow2 = 3,
+
+    /// <summary>Top-row slot 3.</summary>
+    TopRow3 = 4,
+
+    /// <summary>Top-row slot 4 (far right).</summary>
+    TopRow4 = 5,
+
+    /// <summary>Touchpad in the lower section.</summary>
+    Touchpad = 6,
+
+    /// <summary>The hub board all input modules connect through.</summary>
+    HubBoard = 7,
+}

framework-dotnet/Generated/FrameworkModuleDescriptor.cs

@@ -18,7 +18,24 @@ internal readonly ManagedModuleDescriptorSnapshot ToManagedSnapshot()
             (FrameworkDotnet.Enums.FrameworkModuleFlags)flags,
             vendor_id,
             product_id,
-            board_id);
+            board_id,
+            ToManagedPosition());
+    }
+
+    private readonly FrameworkDotnet.Enums.FrameworkInputModulePosition ToManagedPosition()
+    {
+        return position switch
+        {
+            FrameworkInputModulePosition.Unknown => FrameworkDotnet.Enums.FrameworkInputModulePosition.Unknown,
+            FrameworkInputModulePosition.TopRow0 => FrameworkDotnet.Enums.FrameworkInputModulePosition.TopRow0,
+            FrameworkInputModulePosition.TopRow1 => FrameworkDotnet.Enums.FrameworkInputModulePosition.TopRow1,
+            FrameworkInputModulePosition.TopRow2 => FrameworkDotnet.Enums.FrameworkInputModulePosition.TopRow2,
+            FrameworkInputModulePosition.TopRow3 => FrameworkDotnet.Enums.FrameworkInputModulePosition.TopRow3,
+            FrameworkInputModulePosition.TopRow4 => FrameworkDotnet.Enums.FrameworkInputModulePosition.TopRow4,
+            FrameworkInputModulePosition.Touchpad => FrameworkDotnet.Enums.FrameworkInputModulePosition.Touchpad,
+            FrameworkInputModulePosition.HubBoard => FrameworkDotnet.Enums.FrameworkInputModulePosition.HubBoard,
+            _ => FrameworkDotnet.Enums.FrameworkInputModulePosition.Unknown,
+        };
     }
 
     private readonly FrameworkDotnet.Enums.FrameworkModuleIdentity ToManagedIdentity()

framework-dotnet/Snapshots/FrameworkModuleDescriptorSnapshot.cs

@@ -22,7 +22,8 @@ public sealed record FrameworkModuleDescriptorSnapshot
     /// <param name="vendorId">The observed vendor ID, when available.</param>
     /// <param name="productId">The observed product ID, when available.</param>
     /// <param name="boardId">The board-specific numeric identifier, when available.</param>
-    public FrameworkModuleDescriptorSnapshot(FrameworkModuleIdentity identity, FrameworkModuleBus bus, FrameworkModuleSlotKind slotKind, FrameworkModuleConfidence confidence, bool isPresent, int slotIndex, FrameworkModuleFlags flags, uint vendorId, uint productId, int boardId)
+    /// <param name="position">The physical input-deck position, when the module is input-deck-mounted.</param>
+    public FrameworkModuleDescriptorSnapshot(FrameworkModuleIdentity identity, FrameworkModuleBus bus, FrameworkModuleSlotKind slotKind, FrameworkModuleConfidence confidence, bool isPresent, int slotIndex, FrameworkModuleFlags flags, uint vendorId, uint productId, int boardId, FrameworkInputModulePosition position = FrameworkInputModulePosition.Unknown)
     {
         Identity = identity;
         Bus = bus;
@@ -34,6 +35,7 @@ public FrameworkModuleDescriptorSnapshot(FrameworkModuleIdentity identity, Frame
         VendorId = vendorId;
         ProductId = productId;
         BoardId = boardId;
+        Position = position;
     }
 
     /// <summary>
@@ -86,8 +88,14 @@ public FrameworkModuleDescriptorSnapshot(FrameworkModuleIdentity identity, Frame
     /// </summary>
     public int BoardId { get; init; }
 
+    /// <summary>
+    /// Gets the physical input-deck position (Framework Laptop 16), or
+    /// <see cref="FrameworkInputModulePosition.Unknown"/> for modules that are not input-deck-mounted.
+    /// </summary>
+    public FrameworkInputModulePosition Position { get; init; }
+
     public override string ToString()
     {
-        return $"Module Descriptor: Identity: {Identity}, Present: {IsPresent}, Slot Kind: {SlotKind}, Slot Index: {SlotIndex.ToString(CultureInfo.InvariantCulture)}, Bus: {Bus}, Confidence: {Confidence}, Flags: {Flags}, Vendor ID: 0x{VendorId.ToString("X", CultureInfo.InvariantCulture)}, Product ID: 0x{ProductId.ToString("X", CultureInfo.InvariantCulture)}, Board ID: {BoardId.ToString(CultureInfo.InvariantCulture)}";
+        return $"Module Descriptor: Identity: {Identity}, Present: {IsPresent}, Slot Kind: {SlotKind}, Slot Index: {SlotIndex.ToString(CultureInfo.InvariantCulture)}, Position: {Position}, Bus: {Bus}, Confidence: {Confidence}, Flags: {Flags}, Vendor ID: 0x{VendorId.ToString("X", CultureInfo.InvariantCulture)}, Product ID: 0x{ProductId.ToString("X", CultureInfo.InvariantCulture)}, Board ID: {BoardId.ToString(CultureInfo.InvariantCulture)}";
     }
 }