Add configurable PreviewWindow behavior for tab completion (#361)

* Initial plan

* Add TabCompletionPreviewWindow configuration option to Set-PsFzfOption

- Added script-level variable $script:TabCompletionPreviewWindow with default 'hidden|down|right|right:hidden'
- Added TabCompletionPreviewWindow parameter to Set-PsFzfOption function
- Updated Invoke-FzfTabCompletionInner to parse and use the configurable PreviewWindow value
- Added comprehensive tests for the new configuration option
- All 62 tests passing

Co-authored-by: kelleyma49 <2152684+kelleyma49@users.noreply.github.com>

* Add documentation for TabCompletionPreviewWindow option

- Updated Set-PsFzfOption.md with detailed parameter documentation
- Added section in README.md explaining tab completion preview window customization
- Included examples showing different configuration options

Co-authored-by: kelleyma49 <2152684+kelleyma49@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: kelleyma49 <2152684+kelleyma49@users.noreply.github.com>

Author: Copilot

PSFzf.Base.ps1

@@ -149,6 +149,7 @@ $script:OverrideFzfDefaults = $null
 $script:PSReadlineHandlerChords = @()
 $script:TabContinuousTrigger = [IO.Path]::DirectorySeparatorChar.ToString()
 $script:PsReadlineHandlerProviderDelimiter = ','
+$script:TabCompletionPreviewWindow = 'hidden|down|right|right:hidden'
 
 $MyInvocation.MyCommand.ScriptBlock.Module.OnRemove =
 {
@@ -209,7 +210,9 @@ function Set-PsFzfOption {
 		[ScriptBlock]
 		$AltCCommand,
 		[string]
-		$PsReadlineHandlerProviderDelimiter
+		$PsReadlineHandlerProviderDelimiter,
+		[string]
+		$TabCompletionPreviewWindow
 	)
 	if ($PSBoundParameters.ContainsKey('TabExpansion')) {
 		SetTabExpansion $TabExpansion
@@ -260,6 +263,10 @@ function Set-PsFzfOption {
 	if ($PSBoundParameters.ContainsKey('PsReadlineHandlerProviderDelimiter')) {
 		$script:PsReadlineHandlerProviderDelimiter = $PsReadlineHandlerProviderDelimiter
 	}
+
+	if ($PSBoundParameters.ContainsKey('TabCompletionPreviewWindow')) {
+		$script:TabCompletionPreviewWindow = $TabCompletionPreviewWindow
+	}
 }
 
 function Stop-Pipeline {

PSFzf.TabExpansion.ps1

@@ -289,16 +289,21 @@ function script:Invoke-FzfTabCompletionInner() {
         # normalize so path works correctly for Windows:
         $path = $PWD.ProviderPath.Replace('\', '/')
 
+        # Parse the TabCompletionPreviewWindow option to extract initial state and change-preview-window options
+        $previewParts = $script:TabCompletionPreviewWindow -split '\|', 2
+        $initialPreviewState = $previewParts[0]
+        $changePreviewWindowOptions = if ($previewParts.Length -gt 1) { $previewParts[1] } else { 'down|right|right:hidden' }
+
         $arguments = @{
             Layout        = 'reverse'
             Expect        = "$expectTriggers"
-            PreviewWindow = 'hidden'
+            PreviewWindow = $initialPreviewState
         }
         if ($isTabTrigger) {
-            $arguments["Bind"] = @('ctrl-/:change-preview-window:down|right|right:hidden')
+            $arguments["Bind"] = @("ctrl-/:change-preview-window:$changePreviewWindowOptions")
         }
         else {
-            $arguments["Bind"] = @('tab:down', 'btab:up', 'ctrl-/:change-preview-window:down|right|right:hidden')
+            $arguments["Bind"] = @('tab:down', 'btab:up', "ctrl-/:change-preview-window:$changePreviewWindowOptions")
         }
 
         # need to handle parameters differently so PowerShell doesn't parse completion item as a script parameter:

PSFzf.tests.ps1

@@ -650,6 +650,34 @@ Describe "Set-PsFzfOption PsReadlineHandlerProviderDelimiter" {
 	}
 }
 
+Describe "Set-PsFzfOption TabCompletionPreviewWindow" {
+	InModuleScope PsFzf {
+		Context "Default preview window configuration" {
+			It "Should default to 'hidden|down|right|right:hidden'" {
+				# The default preview window configuration should be 'hidden|down|right|right:hidden'
+				$script:TabCompletionPreviewWindow | Should -Be 'hidden|down|right|right:hidden'
+			}
+		}
+
+		Context "Can override preview window configuration" {
+			It "Should allow setting custom preview window configuration" {
+				Set-PsFzfOption -TabCompletionPreviewWindow 'visible|up|left'
+				$script:TabCompletionPreviewWindow | Should -Be 'visible|up|left'
+			}
+
+			It "Should allow setting to hidden with different change options" {
+				Set-PsFzfOption -TabCompletionPreviewWindow 'hidden|up|down|left:hidden'
+				$script:TabCompletionPreviewWindow | Should -Be 'hidden|up|down|left:hidden'
+			}
+
+			It "Should allow setting back to default" {
+				Set-PsFzfOption -TabCompletionPreviewWindow 'hidden|down|right|right:hidden'
+				$script:TabCompletionPreviewWindow | Should -Be 'hidden|down|right|right:hidden'
+			}
+		}
+	}
+}
+
 Describe "Get-EditorLaunch" {
 
 

README.md

@@ -88,6 +88,20 @@ Use the following command to enable tab expansion:
 Set-PsFzfOption -TabExpansion
 ```
 
+### Tab Completion Preview Window
+
+By default, the tab completion preview window starts hidden and can be toggled with <kbd>Ctrl+/</kbd> to cycle through different positions (down, right, or hidden). You can customize this behavior:
+
+```powershell
+# Start with visible preview on the right
+Set-PsFzfOption -TabCompletionPreviewWindow 'right|down|hidden'
+
+# Start hidden and toggle between up, left, and hidden
+Set-PsFzfOption -TabCompletionPreviewWindow 'hidden|up|left|hidden'
+```
+
+The format is `initial_state|change_preview_window_options` where the first part sets whether the preview window is initially visible or hidden, and the rest defines the states to cycle through when pressing <kbd>Ctrl+/</kbd>.
+
 ## Using within a Pipeline
 
 `Invoke-Fzf` works with input from a pipeline. You can use it in the middle of a pipeline, or as part of an expression.

docs/Set-PsFzfOption.md

@@ -271,6 +271,31 @@ Default value: ','
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
+
+### -TabCompletionPreviewWindow
+Specifies the preview window behavior for tab completion. The format is 'initial_state|change_preview_window_options' where the first part sets the initial state of the preview window (e.g., 'hidden' or 'visible'), and the rest is passed to the change-preview-window command (typically bound to Ctrl+/).
+
+```powershell
+# example - start with hidden preview, toggle between up, left, and hidden:
+Set-PsFzfOption -TabCompletionPreviewWindow 'hidden|up|left|hidden'
+
+# example - start with visible preview on the right:
+Set-PsFzfOption -TabCompletionPreviewWindow 'right|up|down|hidden'
+
+# default - start hidden, toggle between down, right, and right:hidden:
+Set-PsFzfOption -TabCompletionPreviewWindow 'hidden|down|right|right:hidden'
+```
+```yaml
+Type: String
+Parameter Sets: (All)
+Aliases: 
+
+Required: False
+Position: Named
+Default value: 'hidden|down|right|right:hidden'
+Accept pipeline input: False
+Accept wildcard characters: False
+```
 ## INPUTS
 ### None