feat: deterministic record lookups, configurable search minimum, and an option-count search threshold [3.x] (#205)

* feat: add selects config block for picker behavior

* fix: order record lookup results deterministically

* fix: make the record-select minimum search length configurable end to end

* feat: only show select search above the configured option threshold

* docs: document the selects config block and the search-box opt-out

* perf: default record lookups to the model key instead of updated_at

Author: ManukMinasyan

config/custom-fields.php

@@ -108,6 +108,33 @@
         'description_max_length' => 255,
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Select & Record Lookup Behavior
+    |--------------------------------------------------------------------------
+    |
+    | searchable_threshold controls when option-backed selects render a search
+    | box. Set it to 0 to always show one, which is the pre-3.8 behavior.
+    |
+    | record_lookup governs the record-select field's initial page and search.
+    | order_column null means the model's key, which is backed by the primary
+    | key index and so costs no more than an unordered query. Naming a column
+    | instead (for example 'updated_at' for most-recently-touched-first) is
+    | supported, but on a large lookup table an unindexed column makes every
+    | render sort the whole tenant, so index it before you switch.
+    |
+    */
+    'selects' => [
+        'searchable_threshold' => 10,
+
+        'record_lookup' => [
+            'order_column' => null,
+            'order_direction' => 'desc',
+            'limit' => 50,
+            'min_search_length' => 2,
+        ],
+    ],
+
     /*
     |--------------------------------------------------------------------------
     | Database Configuration

docs/content/2.essentials/1.configuration.md

@@ -175,6 +175,46 @@ The page must extend `CustomFieldsManagementPage`, and it replaces the packaged
 rather than sitting alongside it — only one management page is registered on the panel,
 so there is no second route to the same screen.
 
+### Select Behavior
+
+Controls when option-backed selects render a search box, and how the record-select field
+orders and pages its lookups:
+
+```php
+'selects' => [
+    'searchable_threshold' => 10,
+
+    'record_lookup' => [
+        'order_column' => null,
+        'order_direction' => 'desc',
+        'limit' => 50,
+        'min_search_length' => 2,
+    ],
+],
+```
+
+| Key | Default | Effect |
+|---|---|---|
+| `searchable_threshold` | `10` | Select and multi-select fields render a search box only when they have more options than this. Set it to `0` to always render one. |
+| `record_lookup.order_column` | `null` | Column the record-select orders its initial page and search results by. `null` means the model's key, which is backed by the primary key index. Name a real column to override. |
+| `record_lookup.order_direction` | `'desc'` | Direction for that column. The model key is always applied after it, so rows sharing a value keep a fixed order. |
+| `record_lookup.limit` | `50` | Rows fetched for the initial page and for each search. |
+| `record_lookup.min_search_length` | `2` | Characters required before a filtered lookup query is issued. Below it, the field shows the unfiltered first page. Both the server and the field's JavaScript read this value. |
+
+::alert{type="info"}
+Before 3.8 every select rendered a search box, including a three-option status field. Set
+`searchable_threshold` to `0` to restore that behavior exactly.
+::
+
+The default exists to make the initial page deterministic without paying for it. Measured on a
+50,000-row lookup table, ordering by the model key plans as an index scan and costs the same as
+the unordered query it replaces, while ordering by an unindexed `updated_at` sorts the whole
+tenant on every render (roughly 176x the time and 205x the buffers). If you prefer
+most-recently-touched-first, set `order_column` to `'updated_at'` and index that column.
+
+When `order_column` is set to `updated_at` and the looked-up model returns `false` from
+`usesTimestamps()`, the model key is used instead, so the order is always deterministic.
+
 ### Database Configuration
 
 Customize table names and paths:

resources/views/forms/record-select-input.blade.php

@@ -9,6 +9,8 @@
     $emptyStateLabel = $getEmptyStateLabel();
     $placeholder = $getPlaceholder() ?? __('Search records...');
     $key = $getKey();
+    $minSearchLength = $getMinSearchLength();
+    $shortSearchMessage = __('Type at least :count characters to search', ['count' => $minSearchLength]);
 
     // Get initial records data for selected values
     $state = $getState() ?? [];
@@ -39,6 +41,7 @@ class="fi-fo-record-select-input-wrp"
             recordsCache: @js($initialRecords),
             initialOptions: @js(array_values($initialOptions)),
             maxVisibleValues: @js($maxVisiblePills),
+            minSearchLength: @js($minSearchLength),
             selectedSnapshot: [],
             activeIndex: -1,
             documentClickListener: null,
@@ -50,7 +53,7 @@ class="fi-fo-record-select-input-wrp"
                 this.state = this.state.filter(v => v && v !== '');
 
                 this.$watch('search', (value) => {
-                    if (value.trim().length >= 2) {
+                    if (value.trim().length >= this.minSearchLength) {
                         this.performSearch();
                     } else {
                         this.searchResults = [];
@@ -143,8 +146,8 @@ class="fi-fo-record-select-input-wrp"
             get sortedOptions() {
                 const searchLower = this.search.toLowerCase().trim();
 
-                // If searching (>=2 chars) and have server results, use those
-                if (searchLower.length >= 2 && this.searchResults.length > 0) {
+                // If searching (at or above the minimum) and have server results, use those
+                if (searchLower.length >= this.minSearchLength && this.searchResults.length > 0) {
                     return this.sortBySelected([...this.searchResults]);
                 }
 
@@ -179,11 +182,11 @@ class="fi-fo-record-select-input-wrp"
 
             get emptyStateMessage() {
                 const searchLength = this.search.trim().length;
-                if (searchLength >= 2) {
+                if (searchLength >= this.minSearchLength) {
                     return '{{ __('No records found') }}';
                 }
                 if (searchLength > 0) {
-                    return '{{ __('Type at least 2 characters to search') }}';
+                    return @js($shortSearchMessage);
                 }
                 if (this.initialOptions.length === 0) {
                     return '{{ __('No records available') }}';
@@ -194,7 +197,7 @@ class="fi-fo-record-select-input-wrp"
             async performSearch() {
                 const query = this.search.trim();
 
-                if (query.length < 2) {
+                if (query.length < this.minSearchLength) {
                     this.searchResults = [];
                     return;
                 }

src/Filament/Integration/Base/AbstractFormComponent.php

@@ -377,6 +377,26 @@ protected function getCustomFieldOptions(CustomField $customField): array
         return $customField->options->pluck('name', 'id')->all();
     }
 
+    /**
+     * Whether an option-backed select should render a search box.
+     *
+     * Filtering for static options happens client-side, so this is a readability
+     * choice rather than a performance one. A threshold of 0 always shows the box,
+     * which is the pre-3.8 behavior.
+     *
+     * @param  array<int|string, string>  $options
+     */
+    protected function shouldBeSearchable(array $options): bool
+    {
+        $threshold = (int) config('custom-fields.selects.searchable_threshold', 10);
+
+        if ($threshold <= 0) {
+            return true;
+        }
+
+        return count($options) > $threshold;
+    }
+
     /**
      * Create the specific Filament field component.
      *

src/Filament/Integration/Components/Forms/MultiSelectComponent.php

@@ -19,7 +19,7 @@ public function create(CustomField $customField): Select
 
         $field = Select::make($customField->getFieldName())
             ->multiple()
-            ->searchable()
+            ->searchable($this->shouldBeSearchable($options))
             ->options($options);
 
         if ($this->hasColorOptionsEnabled($customField)) {

src/Filament/Integration/Components/Forms/RecordSelectInput/RecordSelectInputComponent.php

@@ -151,6 +151,17 @@ public function getMaxVisiblePills(): int
         return $this->evaluate($this->maxVisiblePills);
     }
 
+    /**
+     * Characters required before the field issues a filtered lookup query.
+     *
+     * The view reads the same value, so raising it cannot leave the client
+     * asking for a filtered search the server answers with an unfiltered page.
+     */
+    public function getMinSearchLength(): int
+    {
+        return (int) config('custom-fields.selects.record_lookup.min_search_length', 2);
+    }
+
     /**
      * Get entity configuration for the lookup type.
      */
@@ -168,7 +179,7 @@ public function getEntityConfiguration(): ?EntityConfigurationData
     /**
      * Prepare entity query with common attributes.
      *
-     * @return array{entity: EntityConfigurationData, query: Builder, keyName: string, titleAttribute: string, avatarConfig: ?AvatarConfiguration}|null
+     * @return array{entity: EntityConfigurationData, model: Model, query: Builder, keyName: string, titleAttribute: string, avatarConfig: ?AvatarConfiguration}|null
      */
     private function prepareEntityQuery(): ?array
     {
@@ -178,15 +189,58 @@ private function prepareEntityQuery(): ?array
             return null;
         }
 
+        $model = $entity->createModelInstance();
+
         return [
             'entity' => $entity,
-            'query' => $entity->newQuery(),
-            'keyName' => $entity->createModelInstance()->getKeyName(),
+            'model' => $model,
+            'query' => $model->newQuery(),
+            'keyName' => $model->getKeyName(),
             'titleAttribute' => $entity->getPrimaryAttribute(),
             'avatarConfig' => $entity->getAvatarConfiguration(),
         ];
     }
 
+    /**
+     * Apply a deterministic order to a lookup query.
+     *
+     * Without one, LIMIT returns arbitrary rows and the initial page can change
+     * between renders. The default is the model key: it is backed by the primary
+     * key index, so ordering costs no more than the unordered query it replaces.
+     * Measured on a 50k-row table, ordering by an unindexed column instead costs
+     * roughly 176x the time and 205x the buffers, because every render sorts the
+     * whole tenant.
+     *
+     * A configured column is trusted and the model key is appended to it, so rows
+     * sharing a value still come back in a fixed sequence. Column existence is
+     * resolved without a schema query: a runtime Schema::hasColumn() call would be
+     * a per-request round trip. The one exception is the documented 'updated_at',
+     * which falls back to the key on a model that opts out of timestamps.
+     */
+    private function applyLookupOrder(Builder $query, Model $model): Builder
+    {
+        $column = config('custom-fields.selects.record_lookup.order_column');
+        $direction = (string) config('custom-fields.selects.record_lookup.order_direction', 'desc');
+        $key = $model->getQualifiedKeyName();
+
+        if (! is_string($column) || $column === '') {
+            return $query->orderBy($key, $direction);
+        }
+
+        if ($column === 'updated_at' && ! $model->usesTimestamps()) {
+            return $query->orderBy($key, $direction);
+        }
+
+        return $query
+            ->orderBy($query->qualifyColumn($column), $direction)
+            ->orderBy($key, $direction);
+    }
+
+    private function lookupLimit(): int
+    {
+        return (int) config('custom-fields.selects.record_lookup.limit', 50);
+    }
+
     /**
      * Search for records matching the query.
      *
@@ -200,7 +254,7 @@ public function searchRecords(string $search): array
             return [];
         }
 
-        ['entity' => $entity, 'query' => $query, 'keyName' => $keyName, 'titleAttribute' => $titleAttribute, 'avatarConfig' => $avatarConfig] = $prepared;
+        ['entity' => $entity, 'model' => $model, 'query' => $query, 'keyName' => $keyName, 'titleAttribute' => $titleAttribute, 'avatarConfig' => $avatarConfig] = $prepared;
         $searchAttributes = $entity->getSearchAttributes();
 
         // Try to use resource's search if available
@@ -228,7 +282,9 @@ public function searchRecords(string $search): array
             });
         }
 
-        $records = $query->limit(50)->get();
+        $records = $this->applyLookupOrder($query, $model)
+            ->limit($this->lookupLimit())
+            ->get();
 
         return $this->formatRecordsForJs($records, $keyName, $titleAttribute, $avatarConfig);
     }
@@ -272,9 +328,11 @@ public function getInitialOptions(): array
             return [];
         }
 
-        ['query' => $query, 'keyName' => $keyName, 'titleAttribute' => $titleAttribute, 'avatarConfig' => $avatarConfig] = $prepared;
+        ['model' => $model, 'query' => $query, 'keyName' => $keyName, 'titleAttribute' => $titleAttribute, 'avatarConfig' => $avatarConfig] = $prepared;
 
-        $records = $query->limit(50)->get();
+        $records = $this->applyLookupOrder($query, $model)
+            ->limit($this->lookupLimit())
+            ->get();
 
         return $this->formatRecordsForJs($records, $keyName, $titleAttribute, $avatarConfig);
     }
@@ -324,8 +382,11 @@ private function getAvatarUrl(Model $record, ?AvatarConfiguration $avatarConfig)
     #[Renderless]
     public function getSearchResultsForJs(string $search): array
     {
-        if (mb_strlen($search) < 2) {
-            return [];
+        // Below the minimum, show the unfiltered first page rather than nothing.
+        // Returning [] renders as "no results", which reads as broken for a
+        // one-character search, and is wrong for single-character CJK names.
+        if (mb_strlen($search) < $this->getMinSearchLength()) {
+            return array_values($this->getInitialOptions());
         }
 
         return array_values($this->searchRecords($search));

src/Filament/Integration/Components/Forms/SelectComponent.php

@@ -18,7 +18,7 @@ public function create(CustomField $customField): Select
         $options = $this->getCustomFieldOptions($customField);
 
         $field = Select::make($customField->getFieldName())
-            ->searchable()
+            ->searchable($this->shouldBeSearchable($options))
             ->options($options);
 
         if ($this->hasColorOptionsEnabled($customField)) {