searchbar

# SearchBar Skill

## Overview

This skill provides expert guidance on `SearchBar`, a powerful and highly customizable SwiftUI component for creating native-feeling search experiences across iOS, iPadOS, macOS, and visionOS. It bridges the gap between `UISearchBar` (iOS/visionOS) and native SwiftUI views (macOS), offering a unified API for styling, behavior, and advanced features like search tokens and dynamic suggestions.

## Agent Behavior (Follow These Rules)

1.  **Identify Platform Targets:** SearchBar behaves slightly differently on iOS/visionOS (wraps `UISearchBar`) vs. macOS (custom SwiftUI). Always check or ask for the target platform to provide accurate advice (e.g., specific material effects or token behaviors).
2.  **Prioritize Modifiers:** Direct users to the relevant `SearchBar` modifiers (e.g., `.searchBarStyle`, `.searchBarSuggestions`) rather than suggesting they build custom views from scratch.
3.  **Clarify Availability:** Explicitly mention version requirements (iOS 14+, iOS 16+ for tokens/suggestions) when discussing advanced features.
4.  **Emphasize Localization:** Remind users that `SearchBar` is fully localized and adapts to system languages automatically.
5.  **Contextual Examples:** Provide concise code snippets that illustrate the recommended usage within a View, often with a binding to `@State` for text and tokens.
6.  **Highlight Cross-Platform:** When possible, remind users of SearchBar's cross-platform consistency and how to handle platform-specific differences using `#if os(...)` directives if necessary (though the library handles most internally).

## Project Settings

-   **Deployment Targets:** iOS 14.0+, iPadOS 14.0+, macOS 11.0+, visionOS 1.0+.
-   **Advanced Features:** Tokens and Suggestions require iOS 16.0+, iPadOS 16.0+, visionOS 1.0+. (Suggestions also on macOS 15.0+).
-   **Swift Version:** Swift 5.9+.

## Quick Decision Tree

1.  **Setting up a basic search bar?**
    *   Basic init and setup → `references/SearchBar.md`

2.  **Customizing appearance?**
    *   Changing colors, shape (capsule/rounded) → `references/SearchBarStyle.md`
    *   Using "Glass" or "Solid" materials → `references/SearchBarStyle.md`
    *   Changing the size/scale → `references/SearchBarStyle.md`
    *   Custom icon → `references/SearchBarModifiers.md` (`.searchBarIconView`)

3.  **Configuring behavior?**
    *   Showing/Hiding Cancel or Clear buttons → `references/SearchBarDisplayModes.md`
    *   Handling events (begin/end editing, clear, cancel) → `references/SearchBarModifiers.md`
    *   Focus management → `references/SearchBarModifiers.md` (`.searchBarIsFocused`)

4.  **Using advanced search features (iOS 16+/visionOS)?**
    *   Adding filter tokens (capsules) → `references/SearchBarData.md`
    *   Showing search suggestions → `references/SearchBarData.md`
    *   Enabling automatic suggestion filtering → `references/SearchBarData.md`

## Triage-First Playbook

-   **"My search bar looks different on macOS."**
    *   Explain that macOS uses a pure SwiftUI implementation while iOS uses `UISearchBar`. Styling is consistent but underlying implementation differs.
-   **"Tokens/Suggestions are not showing up."**
    *   Verify the deployment target is iOS 16.0+ or visionOS 1.0+.
    *   Ensure the binding to tokens/suggestions is active and populated.
-   **"How do I change the background color?"**
    *   Use `.searchBarStyle(..., backgroundColor: .red)`. See `references/SearchBarStyle.md`.
-   **"I want to hide the cancel button."**
    *   Use `.searchBarCancelButtonDisplayMode(.never)`. See `references/SearchBarDisplayModes.md`.
-   **"How do I make the search bar glass/transparent?"**
    *   Use `.searchBarMaterial(.glass)`. Note platform/version restrictions (iOS 26+). See `references/SearchBarStyle.md`.

## Core Patterns Reference

### Basic Setup
```swift
SearchBar(text: $text, prompt: "Search...")
    .searchBarStyle(.rounded)
```

### Advanced Styling
```swift
SearchBar(text: $text)
    .searchBarStyle(.capsule, textColor: .white, tint: .blue, backgroundColor: .black.opacity(0.8))
    .searchBarMaterial(.glass) // iOS 26+ (Experimental/Future)
```

### Tokens & Suggestions
```swift
SearchBar(text: $text)
    .searchBarCurrentTokens($tokens)
    .searchBarSuggestions($suggestions)
    .searchBarEnableAutomaticSuggestionsFiltering(true)
```

### Event Handling
```swift
SearchBar(text: $text)
    .searchBarBeginEditingAction { print("Started") }
    .searchBarEndEditingAction { print("Ended") }
    .searchBarCancelButtonAction { print("Cancelled") }
```

## Integration Quick Guide

SearchBar is integrated via Swift Package Manager.

1.  **Add Package Dependency**: In Xcode, go to **File > Add Package Dependency** and enter `https://github.com/SzpakKamil/SearchBar.git`.
2.  **Import**: `import SearchBar` in your Swift files.
3.  **Deployment Targets**: Ensure your project targets iOS 14.0+, macOS 11.0+, visionOS 1.0+.

For detailed setup, see `references/SearchBar.md`.

## Reference Files

-   **`SearchBar.md`** - General overview, setup, and initialization.
-   **`SearchBarModifiers.md`** - Comprehensive list of all modifiers.
-   **`SearchBarStyle.md`** - Styling, materials, corner styles, and scale.
-   **`SearchBarDisplayModes.md`** - Cancel and Clear button behaviors.
-   **`SearchBarData.md`** - Search Tokens and Suggestions.
-   **`_index.md`** - Index of all topics.