mirror of
https://github.com/hanzoai/ui.git
synced 2026-11-21 00:18:41 +00:00
216 lines
5.7 KiB
Plaintext
216 lines
5.7 KiB
Plaintext
---
|
|
title: Desktop Spotlight
|
|
description: A macOS Spotlight-style search dialog with keyboard navigation and category grouping
|
|
component: true
|
|
---
|
|
|
|
<ComponentPreview name="desktop-spotlight-demo" />
|
|
|
|
## Installation
|
|
|
|
<Tabs defaultValue="cli">
|
|
|
|
<TabsList>
|
|
<TabsTrigger value="cli">CLI</TabsTrigger>
|
|
<TabsTrigger value="manual">Manual</TabsTrigger>
|
|
</TabsList>
|
|
|
|
<TabsContent value="cli">
|
|
|
|
<Steps>
|
|
|
|
<Step>Run the following command:</Step>
|
|
|
|
```bash
|
|
npx @hanzo/ui@latest add desktop
|
|
```
|
|
|
|
</Steps>
|
|
|
|
</TabsContent>
|
|
|
|
<TabsContent value="manual">
|
|
|
|
<Steps>
|
|
|
|
<Step>Install dependencies</Step>
|
|
|
|
```bash
|
|
npm install framer-motion lucide-react
|
|
```
|
|
|
|
<Step>Copy and paste the following code into your project</Step>
|
|
|
|
<ComponentSource name="desktop-spotlight" />
|
|
|
|
<Step>Update the import paths to match your project setup</Step>
|
|
|
|
</Steps>
|
|
|
|
</TabsContent>
|
|
|
|
</Tabs>
|
|
|
|
## Usage
|
|
|
|
```tsx
|
|
import { Spotlight, SpotlightItem } from "@hanzo/ui/desktop"
|
|
|
|
const items: SpotlightItem[] = [
|
|
{ id: 'settings', title: 'Settings', category: 'Applications', icon: <Settings /> },
|
|
{ id: 'documents', title: 'Documents', category: 'Folders', icon: <Folder /> },
|
|
{ id: 'music', title: 'Music', category: 'Applications', icon: <Music /> },
|
|
]
|
|
|
|
export function SpotlightDemo() {
|
|
const [isOpen, setIsOpen] = useState(false)
|
|
|
|
return (
|
|
<>
|
|
<button onClick={() => setIsOpen(true)}>Open Spotlight</button>
|
|
|
|
<Spotlight
|
|
isOpen={isOpen}
|
|
onClose={() => setIsOpen(false)}
|
|
items={items}
|
|
onSelect={(item) => {
|
|
console.log('Selected:', item)
|
|
setIsOpen(false)
|
|
}}
|
|
/>
|
|
</>
|
|
)
|
|
}
|
|
```
|
|
|
|
## Props
|
|
|
|
### Spotlight
|
|
|
|
| Prop | Type | Default | Description |
|
|
|------|------|---------|-------------|
|
|
| `isOpen` | `boolean` | - | Controls visibility of the spotlight dialog |
|
|
| `onClose` | `() => void` | - | Callback when spotlight is closed |
|
|
| `items` | `SpotlightItem[]` | - | Array of searchable items |
|
|
| `onSelect` | `(item: SpotlightItem) => void` | - | Callback when an item is selected |
|
|
| `placeholder` | `string` | `'Search...'` | Search input placeholder text |
|
|
|
|
### SpotlightItem
|
|
|
|
| Property | Type | Description |
|
|
|----------|------|-------------|
|
|
| `id` | `string` | Unique identifier for the item |
|
|
| `title` | `string` | Display title |
|
|
| `subtitle` | `string` | Optional subtitle/description text |
|
|
| `icon` | `ReactNode` | Optional icon to display |
|
|
| `category` | `string` | Category for grouping |
|
|
| `keywords` | `string[]` | Optional search keywords |
|
|
| `action` | `() => void` | Optional action callback |
|
|
|
|
## Features
|
|
|
|
- **Fuzzy Search**: Real-time filtering as you type
|
|
- **Category Grouping**: Items organized by category headers
|
|
- **Keyboard Navigation**: Arrow keys to navigate, Enter to select, Escape to close
|
|
- **Focus Management**: Auto-focus on open, proper focus trap
|
|
- **Smooth Animations**: Fade and scale transitions
|
|
|
|
## Examples
|
|
|
|
### Application Launcher
|
|
|
|
```tsx
|
|
import { Spotlight, SpotlightItem, useKeyboardShortcuts } from "@hanzo/ui/desktop"
|
|
import {
|
|
Terminal,
|
|
Chrome,
|
|
Mail,
|
|
Calendar,
|
|
Music,
|
|
Settings,
|
|
Folder
|
|
} from "lucide-react"
|
|
|
|
const apps: SpotlightItem[] = [
|
|
{ id: 'terminal', label: 'Terminal', category: 'Applications', icon: <Terminal className="h-5 w-5" /> },
|
|
{ id: 'safari', label: 'Safari', category: 'Applications', icon: <Chrome className="h-5 w-5" /> },
|
|
{ id: 'mail', label: 'Mail', category: 'Applications', icon: <Mail className="h-5 w-5" /> },
|
|
{ id: 'calendar', label: 'Calendar', category: 'Applications', icon: <Calendar className="h-5 w-5" /> },
|
|
{ id: 'music', label: 'Music', category: 'Applications', icon: <Music className="h-5 w-5" /> },
|
|
{ id: 'settings', label: 'System Preferences', category: 'Applications', icon: <Settings className="h-5 w-5" /> },
|
|
{ id: 'documents', label: 'Documents', category: 'Folders', icon: <Folder className="h-5 w-5" /> },
|
|
{ id: 'downloads', label: 'Downloads', category: 'Folders', icon: <Folder className="h-5 w-5" /> },
|
|
]
|
|
|
|
export function AppLauncher() {
|
|
const [isOpen, setIsOpen] = useState(false)
|
|
|
|
// ⌘+Space to open (like macOS)
|
|
useKeyboardShortcuts([
|
|
{ key: ' ', meta: true, action: () => setIsOpen(true) }
|
|
])
|
|
|
|
return (
|
|
<Spotlight
|
|
isOpen={isOpen}
|
|
onClose={() => setIsOpen(false)}
|
|
items={apps}
|
|
placeholder="Search applications..."
|
|
onSelect={(item) => {
|
|
console.log('Launch:', item.label)
|
|
setIsOpen(false)
|
|
}}
|
|
/>
|
|
)
|
|
}
|
|
```
|
|
|
|
### Command Palette
|
|
|
|
```tsx
|
|
import { Spotlight, SpotlightItem } from "@hanzo/ui/desktop"
|
|
import {
|
|
Save,
|
|
Copy,
|
|
Scissors,
|
|
Clipboard,
|
|
Undo,
|
|
Redo
|
|
} from "lucide-react"
|
|
|
|
const commands: SpotlightItem[] = [
|
|
{ id: 'save', label: 'Save', category: 'File', icon: <Save />, shortcut: '⌘S' },
|
|
{ id: 'copy', label: 'Copy', category: 'Edit', icon: <Copy />, shortcut: '⌘C' },
|
|
{ id: 'cut', label: 'Cut', category: 'Edit', icon: <Scissors />, shortcut: '⌘X' },
|
|
{ id: 'paste', label: 'Paste', category: 'Edit', icon: <Clipboard />, shortcut: '⌘V' },
|
|
{ id: 'undo', label: 'Undo', category: 'Edit', icon: <Undo />, shortcut: '⌘Z' },
|
|
{ id: 'redo', label: 'Redo', category: 'Edit', icon: <Redo />, shortcut: '⌘⇧Z' },
|
|
]
|
|
|
|
export function CommandPalette() {
|
|
const [isOpen, setIsOpen] = useState(false)
|
|
|
|
return (
|
|
<Spotlight
|
|
isOpen={isOpen}
|
|
onClose={() => setIsOpen(false)}
|
|
items={commands}
|
|
placeholder="Type a command..."
|
|
onSelect={(item) => {
|
|
console.log('Execute:', item.id)
|
|
setIsOpen(false)
|
|
}}
|
|
/>
|
|
)
|
|
}
|
|
```
|
|
|
|
## Keyboard Shortcuts
|
|
|
|
| Shortcut | Action |
|
|
|----------|--------|
|
|
| `↑` / `↓` | Navigate between items |
|
|
| `Enter` | Select highlighted item |
|
|
| `Escape` | Close spotlight |
|
|
| `⌘K` / `⌘Space` | Open spotlight (when configured) |
|