[#7] Added fuzzy matching, highlighting and paging to the choice widgets.

README.md

@@ -210,7 +210,7 @@ With `revealable()` on, pressing Tab in the editor reveals the value and the hin
 
 ### Select
 
-Single choice from a list. Up/Down move, Enter accepts the highlighted option. Pass `default` (an option key) to start on an option other than the first.
+Single choice from a list. Up/Down move, Enter accepts the highlighted option. Pass `default` (an option key) to start on an option other than the first. Long lists page around the cursor - set the window with `->pageSize()`.
 
 ```php
 $p->select('profile', 'Install profile')->default('minimal')->options(['standard' => 'Standard', 'minimal' => 'Minimal', 'demo_umami' => 'Demo Umami']);
@@ -236,7 +236,7 @@ $p->select('profile', 'Install profile')->default('minimal')->options(['standard
 
 ### MultiSelect
 
-Multiple choice from a checkbox list. Space toggles the highlighted option, typing narrows the list, Right selects and Left deselects everything visible, Enter accepts. Pass `default` (a list of option keys) to pre-check options - ideal for opt-out lists.
+Multiple choice from a checkbox list. Space toggles the highlighted option, typing narrows the list by substring, Right selects and Left deselects everything visible, Enter accepts. Pass `default` (a list of option keys) to pre-check options - ideal for opt-out lists. Long lists page around the cursor - set the window with `->pageSize()`.
 
 ```php
 $p->multiselect('services', 'Services')->default(['redis'])->options(['redis' => 'Redis', 'solr' => 'Solr', 'clamav' => 'ClamAV']);
@@ -262,7 +262,7 @@ $p->multiselect('services', 'Services')->default(['redis'])->options(['redis' =>
 
 ### Suggest
 
-Free text with autocomplete over a fixed option set: type anything, Up/Down highlight a matching suggestion, Enter accepts the highlighted suggestion or the typed text as-is.
+Free text with autocomplete over a fixed option set: as you type, the suggestions are fuzzy-matched and ranked by relevance with the matched characters highlighted; Up/Down highlight a suggestion, Enter accepts the highlighted suggestion or the typed text as-is. Long lists page around the cursor - set the window with `->pageSize()`.
 
 ```php
 $p->suggest('php_version', 'PHP version')->default('8.4')->options(['8.1' => '8.1', '8.2' => '8.2', '8.3' => '8.3', '8.4' => '8.4']);
@@ -288,10 +288,10 @@ $p->suggest('php_version', 'PHP version')->default('8.4')->options(['8.1' => '8.
 
 ### Search
 
-Single choice with a visible type-to-filter line above the options: typing narrows the labels, Up/Down move, Enter accepts the highlighted option's key.
+Single choice with a visible filter line above the options: typing fuzzy-matches and ranks the labels - exact and prefix matches lead, looser subsequence matches follow - and highlights the matched characters; Up/Down move, Enter accepts the highlighted option's key. Long lists page around the cursor - set the window with `->pageSize()`.
 
 ```php
-$p->search('timezone', 'Timezone')->default('london')->options(['utc' => 'UTC', 'london' => 'Europe/London', 'paris' => 'Europe/Paris', 'sydney' => 'Australia/Sydney']);
+$p->search('timezone', 'Timezone')->default('london')->pageSize(8)->options(['utc' => 'UTC', 'london' => 'Europe/London', 'paris' => 'Europe/Paris', 'sydney' => 'Australia/Sydney']);
 ```
 
 <table>
@@ -314,7 +314,7 @@ $p->search('timezone', 'Timezone')->default('london')->options(['utc' => 'UTC',
 
 ### MultiSearch
 
-A multi-select whose type-to-filter query is shown as a search line: type to narrow, Space toggles, Enter accepts the checked set.
+A multi-select whose filter query is shown as a search line: typing fuzzy-matches and ranks the options with the matched characters highlighted, Space toggles, Enter accepts the checked set. Long lists page around the cursor - set the window with `->pageSize()`.
 
 ```php
 $p->multisearch('services', 'Services')->default(['redis'])->options(['redis' => 'Redis', 'solr' => 'Solr', 'clamav' => 'ClamAV', 'memcached' => 'Memcached']);

src/Builder/FieldBuilder.php

@@ -131,6 +131,11 @@ final class FieldBuilder {
    */
   protected bool $pickerShowHidden = FALSE;
 
+  /**
+   * Choice widgets only: the visible page size, when declared.
+   */
+  protected ?int $pageSize = NULL;
+
   /**
    * Construct a field builder.
    *
@@ -375,6 +380,32 @@ public function showHidden(bool $show = TRUE): self {
     return $this;
   }
 
+  /**
+   * Choice widgets only: bound the visible option list to a page size.
+   *
+   * Longer lists page around the cursor rather than overflowing the viewport.
+   * Honoured by the select, multiselect, suggest, search and multisearch
+   * widgets; ignored by other types.
+   *
+   * @param int $size
+   *   The number of option rows shown at once; must be positive.
+   *
+   * @return $this
+   *   The builder.
+   *
+   * @throws \DrevOps\Tui\Config\ConfigException
+   *   When the size is not positive.
+   */
+  public function pageSize(int $size): self {
+    if ($size < 1) {
+      throw new ConfigException(sprintf('Field "%s" declares a non-positive page size %d.', $this->id, $size));
+    }
+
+    $this->pageSize = $size;
+
+    return $this;
+  }
+
   /**
    * Set the conditional-visibility rule.
    *
@@ -562,6 +593,7 @@ public function build(): Field {
       $this->pickerStart,
       $this->pickerExtensions,
       $this->pickerShowHidden,
+      $this->pageSize,
     );
   }
 

src/Config/Field.php

@@ -81,6 +81,10 @@
    *   (dot-less, case-insensitive); empty allows every extension.
    * @param bool $pickerShowHidden
    *   File picker only: whether dot-entries are shown when the browser opens.
+   * @param int|null $pageSize
+   *   Choice widgets only: how many option rows show at once before the list
+   *   pages; NULL uses the widget default. A purely visual bound - it does not
+   *   constrain a headless value, so it is absent from the machine schema.
    */
   public function __construct(
     public string $id,
@@ -104,6 +108,7 @@ public function __construct(
     public string $pickerStart = '',
     public array $pickerExtensions = [],
     public bool $pickerShowHidden = FALSE,
+    public ?int $pageSize = NULL,
   ) {
     $this->options = Option::list($options);
   }

src/Theme/DefaultTheme.php

@@ -335,6 +335,13 @@ public function highlight(string $text): string {
     return $this->paint($this->isDark ? '1;36' : '1;34', $text);
   }
 
+  /**
+   * {@inheritdoc}
+   */
+  public function highlightMatch(string $text): string {
+    return $this->paint($this->isDark ? '1;33' : '1;35', $text);
+  }
+
   /**
    * {@inheritdoc}
    */

src/Theme/ThemeInterface.php

@@ -127,6 +127,11 @@ public function indicator(string $text): string;
    */
   public function highlight(string $text): string;
 
+  /**
+   * A run of query-matched characters within an option label.
+   */
+  public function highlightMatch(string $text): string;
+
   /**
    * A non-selectable group heading in an option list.
    */

src/Widget/AbstractWidget.php

@@ -9,6 +9,8 @@
 use DrevOps\Tui\Input\KeyMapManager;
 use DrevOps\Tui\Input\Scope;
 use DrevOps\Tui\Input\ScopedKeyMap;
+use DrevOps\Tui\Render\Scroller;
+use DrevOps\Tui\Render\Viewport;
 use DrevOps\Tui\Theme\ThemeInterface;
 
 /**
@@ -18,6 +20,11 @@
  */
 abstract class AbstractWidget implements WidgetInterface {
 
+  /**
+   * The page size applied when a field declares none.
+   */
+  public const int DEFAULT_PAGE_SIZE = 10;
+
   /**
    * The resolved key bindings for this widget's scope.
    *
@@ -26,6 +33,21 @@ abstract class AbstractWidget implements WidgetInterface {
    */
   protected ?ScopedKeyMap $scoped = NULL;
 
+  /**
+   * The number of option rows shown at once before the list pages.
+   */
+  protected int $pageSize = self::DEFAULT_PAGE_SIZE;
+
+  /**
+   * The index of the first visible option row under paging.
+   */
+  protected int $offset = 0;
+
+  /**
+   * The fuzzy matcher, created on first use.
+   */
+  protected ?Matcher $matcher = NULL;
+
   /**
    * Whether a valid value has been accepted.
    */
@@ -189,6 +211,125 @@ protected function renderRadioRow(ThemeInterface $theme, string $label, bool $cu
     return $theme->radio($current) . ' ' . $this->highlightLabel($theme, $label, $current);
   }
 
+  /**
+   * The shared fuzzy matcher.
+   *
+   * @return \DrevOps\Tui\Widget\Matcher
+   *   The matcher.
+   */
+  protected function matcher(): Matcher {
+    return $this->matcher ??= new Matcher();
+  }
+
+  /**
+   * Resolve the effective page size, rejecting a non-positive declared value.
+   *
+   * The builder rejects a non-positive page size, but a widget may be
+   * constructed directly, so the invariant is enforced here too.
+   *
+   * @param int|null $pageSize
+   *   The declared page size, or NULL to use the default.
+   *
+   * @return int
+   *   The effective page size.
+   *
+   * @throws \InvalidArgumentException
+   *   When a declared page size is not positive.
+   */
+  protected function resolvePageSize(?int $pageSize): int {
+    if ($pageSize !== NULL && $pageSize < 1) {
+      throw new \InvalidArgumentException(sprintf('Page size must be a positive integer, %d given.', $pageSize));
+    }
+
+    return $pageSize ?? self::DEFAULT_PAGE_SIZE;
+  }
+
+  /**
+   * Compute the cursor-visible paging window, storing its offset.
+   *
+   * @param int $total
+   *   The total number of option rows.
+   * @param int $cursor
+   *   The cursor row index (a negative cursor pins the window to the top).
+   *
+   * @return \DrevOps\Tui\Render\Viewport
+   *   The window: its offset and whether rows are scrolled off above or below.
+   */
+  protected function pageViewport(int $total, int $cursor): Viewport {
+    $viewport = (new Scroller())->compute($total, $this->pageSize, max(0, $cursor), $this->offset);
+    $this->offset = $viewport->offset;
+
+    return $viewport;
+  }
+
+  /**
+   * Style an option label, emphasising the query-matched characters.
+   *
+   * The label is split into runs of matched and unmatched characters, each run
+   * styled on its own so no SGR code nests inside another: matched runs get the
+   * match colour, and on the cursor row the rest keeps the highlight colour.
+   * With no matched positions this is exactly {@see highlightLabel()}.
+   *
+   * @param \DrevOps\Tui\Theme\ThemeInterface $theme
+   *   The theme.
+   * @param string $label
+   *   The option label.
+   * @param list<int> $positions
+   *   The zero-based indices of the matched characters.
+   * @param bool $current
+   *   Whether the option's row holds the cursor.
+   *
+   * @return string
+   *   The styled label.
+   */
+  protected function renderMatchedLabel(ThemeInterface $theme, string $label, array $positions, bool $current): string {
+    if ($positions === []) {
+      return $this->highlightLabel($theme, $label, $current);
+    }
+
+    $matched = array_fill_keys($positions, TRUE);
+    $out = '';
+    $run = '';
+    $run_matched = FALSE;
+
+    foreach (mb_str_split($label) as $index => $char) {
+      $is_matched = isset($matched[$index]);
+
+      if ($run !== '' && $is_matched !== $run_matched) {
+        $out .= $this->styleRun($theme, $run, $run_matched, $current);
+        $run = '';
+      }
+
+      $run .= $char;
+      $run_matched = $is_matched;
+    }
+
+    return $out . $this->styleRun($theme, $run, $run_matched, $current);
+  }
+
+  /**
+   * Style one run of same-kind characters for {@see renderMatchedLabel()}.
+   *
+   * @param \DrevOps\Tui\Theme\ThemeInterface $theme
+   *   The theme.
+   * @param string $run
+   *   The run of characters.
+   * @param bool $matched
+   *   Whether the run's characters matched the query.
+   * @param bool $current
+   *   Whether the option's row holds the cursor.
+   *
+   * @return string
+   *   The styled run.
+   */
+  protected function styleRun(ThemeInterface $theme, string $run, bool $matched, bool $current): string {
+    if ($matched) {
+      return $theme->highlightMatch($run);
+    }
+
+    return $current ? $theme->highlight($run) : $run;
+  }
+
   /**
    * Validate and, when valid, transform a value and complete the widget.
    *

src/Widget/MatchResult.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DrevOps\Tui\Widget;
+
+/**
+ * The outcome of matching a query against a candidate label.
+ *
+ * Carries the relevance score used to rank a candidate against its peers and
+ * the label character indices the query matched, used to highlight them.
+ *
+ * @package DrevOps\Tui\Widget
+ */
+final readonly class MatchResult {
+
+  /**
+   * Construct a match result.
+   *
+   * @param int $score
+   *   The relevance score: higher ranks ahead. Tiered so an exact match always
+   *   outranks a prefix, a prefix a substring, and a substring a looser
+   *   subsequence, whatever the finer refinement within a tier.
+   * @param list<int> $positions
+   *   The zero-based indices of the matched characters in the candidate, in
+   *   ascending order, for highlighting.
+   */
+  public function __construct(
+    public int $score,
+    public array $positions,
+  ) {
+  }
+
+}

src/Widget/MatchTier.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace DrevOps\Tui\Widget;
+
+/**
+ * How closely a candidate matches a query, coarsest band first.
+ *
+ * A tighter tier always outranks a looser one regardless of the finer
+ * within-tier refinement, so the tier's weight dominates the match score.
+ *
+ * @package DrevOps\Tui\Widget
+ */
+enum MatchTier {
+
+  // The candidate equals the query (case-insensitively).
+  case Exact;
+
+  // The query is a prefix of the candidate.
+  case Prefix;
+
+  // The query appears in the candidate as a contiguous substring.
+  case Substring;
+
+  // The query's characters appear in order but not contiguously.
+  case Subsequence;
+
+  /**
+   * The ranking weight: a higher weight ranks ahead.
+   *
+   * @return int
+   *   The weight, from 4 (exact) down to 1 (subsequence).
+   */
+  public function weight(): int {
+    return match ($this) {
+      self::Exact => 4,
+      self::Prefix => 3,
+      self::Substring => 2,
+      self::Subsequence => 1,
+    };
+  }
+
+}