@qikbar/qikbar 0.0.24 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +92 -0
  3. package/dist/ai/agent.d.ts +42 -0
  4. package/dist/ai/byok.d.ts +29 -0
  5. package/dist/ai/index.d.ts +8 -0
  6. package/dist/ai/providers.d.ts +82 -0
  7. package/dist/ai/sse.d.ts +9 -0
  8. package/dist/ai.js +36 -0
  9. package/dist/ai.js.map +7 -0
  10. package/dist/chunks/bar-D5CSPT3U.js +2031 -0
  11. package/dist/chunks/bar-D5CSPT3U.js.map +7 -0
  12. package/dist/chunks/chunk-2ADXL7KQ.js +358 -0
  13. package/dist/chunks/chunk-2ADXL7KQ.js.map +7 -0
  14. package/dist/chunks/chunk-6TC6G2C5.js +107 -0
  15. package/dist/chunks/chunk-6TC6G2C5.js.map +7 -0
  16. package/dist/chunks/chunk-HBBSETRF.js +153 -0
  17. package/dist/chunks/chunk-HBBSETRF.js.map +7 -0
  18. package/dist/chunks/chunk-I77YSUJN.js +104 -0
  19. package/dist/chunks/chunk-I77YSUJN.js.map +7 -0
  20. package/dist/chunks/chunk-IJ3WUM3T.js +544 -0
  21. package/dist/chunks/chunk-IJ3WUM3T.js.map +7 -0
  22. package/dist/chunks/chunk-MPTP2EWW.js +8 -0
  23. package/dist/chunks/chunk-MPTP2EWW.js.map +7 -0
  24. package/dist/chunks/chunk-N4Y2Z6YD.js +69 -0
  25. package/dist/chunks/chunk-N4Y2Z6YD.js.map +7 -0
  26. package/dist/chunks/chunk-PQEHV3D4.js +124 -0
  27. package/dist/chunks/chunk-PQEHV3D4.js.map +7 -0
  28. package/dist/chunks/chunk-VXTYD56F.js +453 -0
  29. package/dist/chunks/chunk-VXTYD56F.js.map +7 -0
  30. package/dist/chunks/chunk-YCVJQ7U3.js +52 -0
  31. package/dist/chunks/chunk-YCVJQ7U3.js.map +7 -0
  32. package/dist/core/define.d.ts +40 -0
  33. package/dist/core/frecency.d.ts +16 -0
  34. package/dist/core/hotkeys.d.ts +39 -0
  35. package/dist/core/lazy.d.ts +48 -0
  36. package/dist/core/search.d.ts +42 -0
  37. package/dist/core/storage.d.ts +5 -0
  38. package/dist/core/types.d.ts +601 -0
  39. package/dist/extensions/index.d.ts +30 -0
  40. package/dist/extensions/math.d.ts +14 -0
  41. package/dist/extensions.js +476 -0
  42. package/dist/extensions.js.map +7 -0
  43. package/dist/index.d.ts +27 -0
  44. package/dist/index.js +67 -0
  45. package/dist/index.js.map +7 -0
  46. package/dist/qikbar.global.js +259 -0
  47. package/dist/qikbar.global.js.map +7 -0
  48. package/dist/react/index.d.ts +66 -0
  49. package/dist/react.js +119 -0
  50. package/dist/react.js.map +7 -0
  51. package/dist/server/index.d.ts +47 -0
  52. package/dist/server.js +93 -0
  53. package/dist/server.js.map +7 -0
  54. package/dist/styles.css +222 -0
  55. package/dist/theme.d.ts +5 -0
  56. package/dist/theme.js +20 -0
  57. package/dist/theme.js.map +7 -0
  58. package/dist/ui/bar.d.ts +252 -0
  59. package/dist/ui/dom.d.ts +21 -0
  60. package/dist/ui/icons.d.ts +88 -0
  61. package/dist/ui/markdown.d.ts +8 -0
  62. package/dist/ui/nav.d.ts +8 -0
  63. package/dist/ui/styles.d.ts +6 -0
  64. package/dist/ui/themes.d.ts +27 -0
  65. package/dist/ui/views.d.ts +148 -0
  66. package/dist/utils.d.ts +10 -0
  67. package/dist/utils.js +50 -0
  68. package/dist/utils.js.map +7 -0
  69. package/package.json +88 -43
  70. package/dist/qikbar.es.js +0 -8748
  71. package/dist/qikbar.umd.js +0 -113
  72. package/dist/types/boot.d.ts +0 -72
  73. package/dist/types/index.d.ts +0 -1
  74. package/dist/types/init.d.ts +0 -2
  75. package/dist/types/main.d.ts +0 -4
  76. package/dist/types/shared/AsyncRoot.d.ts +0 -5
  77. package/dist/types/shared/CommandFooter.d.ts +0 -5
  78. package/dist/types/shared/Crumbs.d.ts +0 -6
  79. package/dist/types/shared/Details.d.ts +0 -3
  80. package/dist/types/shared/ErrorBoundary.d.ts +0 -15
  81. package/dist/types/shared/Icon.d.ts +0 -4
  82. package/dist/types/shared/List.d.ts +0 -30
  83. package/dist/types/shared/Qikbar.d.ts +0 -5
  84. package/dist/types/shared/Root.d.ts +0 -4
  85. package/dist/types/shared/Search.d.ts +0 -1
  86. package/dist/types/shared/commandContext.d.ts +0 -8
  87. package/dist/types/shared/useDebounce.d.ts +0 -1
  88. package/dist/types/utils/liquid.d.ts +0 -4
  89. package/dist/types/vite-env.d.ts +0 -1
@@ -0,0 +1,601 @@
1
+ /**
2
+ * Public types for Qikbar.
3
+ *
4
+ * Everything in Qikbar is plain data: commands, items, actions and views are
5
+ * objects you can create in any framework (or none) and that an AI model can
6
+ * reason about.
7
+ */
8
+ export type Awaitable<T> = T | Promise<T>;
9
+ /**
10
+ * What `run`, actions and form submissions may return:
11
+ * a `View` to push it, `false` to keep the bar open, anything else to close.
12
+ */
13
+ export type RunResult = View | false | void | undefined | null | (object & {});
14
+ /**
15
+ * An icon. Strings are interpreted as:
16
+ * - a built-in icon name (`"search"`, `"settings"`, …, see `icons`)
17
+ * - an image URL (`https://…`, `/…`, `./…`, `data:…`)
18
+ * - inline SVG markup (`<svg …>`; treated as trusted HTML)
19
+ * - anything else is rendered as text (emoji, a letter, …)
20
+ *
21
+ * Pass a DOM `Node` (or a function returning one) for full control.
22
+ */
23
+ export type Icon = string | Node | (() => Node) | {
24
+ url: string;
25
+ alt?: string;
26
+ } | {
27
+ color: string;
28
+ icon?: string;
29
+ };
30
+ export type Color = 'default' | 'gray' | 'blue' | 'green' | 'yellow' | 'orange' | 'red' | 'purple' | 'pink' | (string & {});
31
+ export interface Accessory {
32
+ text?: string;
33
+ icon?: Icon;
34
+ /** Rendered as a colored pill. */
35
+ tag?: string | {
36
+ value: string;
37
+ color?: Color;
38
+ };
39
+ /** Rendered as keyboard keys, e.g. `"mod+shift+p"`. */
40
+ kbd?: string;
41
+ /** Rendered relative ("3h ago"). */
42
+ date?: Date | number | string;
43
+ tooltip?: string;
44
+ }
45
+ /** Context available to every `run`, action and dynamic view. */
46
+ export interface Context {
47
+ /** The Qikbar instance. */
48
+ readonly bar: QikbarInstance;
49
+ /** Current search text of the active view. */
50
+ readonly query: string;
51
+ /** Aborted when the view is popped, the bar closes or the query changes. */
52
+ readonly signal: AbortSignal;
53
+ /** Values from the extension's `preferences` (empty for app commands). */
54
+ readonly preferences: Record<string, any>;
55
+ /** Values entered for the command's `arguments`. */
56
+ readonly arguments: Record<string, string>;
57
+ /** Namespaced persistent storage (localStorage by default). */
58
+ readonly storage: ScopedStorage;
59
+ /** The configured AI client, if any. */
60
+ readonly ai: AIClient | undefined;
61
+ /** Push a view onto the navigation stack. */
62
+ push(view: View): void;
63
+ /** Go back one view. */
64
+ pop(): void;
65
+ /** Replace the current view (use to re-render a view with new data). */
66
+ render(view: View): void;
67
+ /** Close the bar. */
68
+ close(): void;
69
+ /** Navigate within your app using the configured router. */
70
+ navigate(href: string, options?: {
71
+ newTab?: boolean;
72
+ }): void;
73
+ /** Open an external URL in a new tab. */
74
+ openUrl(url: string): void;
75
+ /** Copy text to the clipboard. Resolves to `true` on success. */
76
+ copy(text: string): Promise<boolean>;
77
+ /** Show a toast. Shown in the footer while open, or as a floating HUD when closed. */
78
+ toast(options: ToastOptions | string): ToastHandle;
79
+ /** Ask the user to confirm something. */
80
+ confirm(options: ConfirmOptions | string): Promise<boolean>;
81
+ /** Set the search text. */
82
+ setQuery(query: string): void;
83
+ }
84
+ export interface ToastOptions {
85
+ title: string;
86
+ message?: string;
87
+ style?: 'success' | 'failure' | 'loading' | 'info';
88
+ /** Milliseconds before the toast hides. `0` keeps it. Default 2500 (loading toasts persist). */
89
+ duration?: number;
90
+ }
91
+ export interface ToastHandle {
92
+ update(options: Partial<ToastOptions>): void;
93
+ hide(): void;
94
+ }
95
+ export interface ConfirmOptions {
96
+ title: string;
97
+ message?: string;
98
+ confirmLabel?: string;
99
+ cancelLabel?: string;
100
+ destructive?: boolean;
101
+ }
102
+ export interface Action {
103
+ id?: string;
104
+ title: string;
105
+ icon?: Icon;
106
+ /** Shortcut that triggers the action while the bar is open, e.g. `"mod+c"`. */
107
+ shortcut?: string;
108
+ /** Groups actions in the action panel. */
109
+ section?: string;
110
+ style?: 'default' | 'destructive';
111
+ /**
112
+ * Called when the action runs. Return a `View` to push it.
113
+ * By default the bar closes afterwards; return `false` (or set `keepOpen`) to keep it open.
114
+ */
115
+ run(ctx: Context): Awaitable<RunResult>;
116
+ keepOpen?: boolean;
117
+ }
118
+ /** A row in a list or grid, or a command at the root. */
119
+ export interface Item {
120
+ id?: string;
121
+ title: string;
122
+ subtitle?: string;
123
+ /** Longer description. Shown in detail panes and given to AI models. */
124
+ description?: string;
125
+ icon?: Icon;
126
+ /** Extra search terms. */
127
+ keywords?: string[];
128
+ /** Section heading the item is grouped under. */
129
+ section?: string;
130
+ accessories?: Accessory[];
131
+ /** Image URL used by grid views. */
132
+ image?: string;
133
+ /** Markdown shown in the side panel when the list has `detail: true`. */
134
+ detail?: string | (() => Awaitable<string>);
135
+ /** Shorthand primary action: navigate to an in-app route. */
136
+ href?: string;
137
+ /** Shorthand primary action: open an external URL in a new tab. */
138
+ url?: string;
139
+ /** Shorthand primary action: run code. Return a `View` to push it. */
140
+ run?: (ctx: Context) => Awaitable<RunResult>;
141
+ /** Shorthand primary action: push a view. */
142
+ view?: View | ((ctx: Context) => Awaitable<View>);
143
+ /** Additional actions. The first action is the primary action (↵), the second is secondary (⌘↵). */
144
+ actions?: Action[];
145
+ /** Global keyboard shortcut that runs this item even when the bar is closed, e.g. `"mod+shift+d"` or `"g s"`. */
146
+ shortcut?: string;
147
+ /** Hide the item unless this returns true (evaluated on open). */
148
+ when?: () => boolean;
149
+ /** Only show this item when the user has typed something. */
150
+ searchOnly?: boolean;
151
+ /** Ranking boost (0–1). */
152
+ priority?: number;
153
+ /** Arguments asked for inline before running (like Raycast arguments). */
154
+ arguments?: Argument[];
155
+ /** Disable frecency tracking for this item. */
156
+ noHistory?: boolean;
157
+ }
158
+ /** Commands are items that live at the root of the bar. */
159
+ export type Command = Item;
160
+ export interface Argument {
161
+ name: string;
162
+ placeholder?: string;
163
+ type?: 'text' | 'password' | 'dropdown';
164
+ required?: boolean;
165
+ options?: {
166
+ title: string;
167
+ value: string;
168
+ }[];
169
+ }
170
+ export interface LoadArgs {
171
+ query: string;
172
+ signal: AbortSignal;
173
+ ctx: Context;
174
+ }
175
+ export type ItemsLoader = (args: LoadArgs) => Awaitable<Item[]> | AsyncIterable<Item[]>;
176
+ interface BaseView {
177
+ /** Shown in the breadcrumb. */
178
+ title?: string;
179
+ /** Placeholder for the search input. */
180
+ placeholder?: string;
181
+ /** Actions available for every item in this view. */
182
+ actions?: Action[];
183
+ /** Called when the view is removed. */
184
+ onClose?: () => void;
185
+ }
186
+ export interface EmptyView {
187
+ title: string;
188
+ description?: string;
189
+ icon?: Icon;
190
+ }
191
+ export interface ListView extends BaseView {
192
+ type: 'list';
193
+ /** Static items, or a loader called with the search text (debounced). */
194
+ items: Item[] | ItemsLoader;
195
+ /**
196
+ * Fuzzy-filter items locally. Defaults to `true` for static arrays and `false`
197
+ * for loaders (the loader is expected to filter on `query`).
198
+ */
199
+ filter?: boolean;
200
+ /** Debounce for loaders, in ms. Default 120. */
201
+ debounce?: number;
202
+ /** Show a markdown side panel for the selected item (`item.detail`). */
203
+ detail?: boolean;
204
+ emptyView?: EmptyView;
205
+ /** Initial search text. */
206
+ query?: string;
207
+ }
208
+ export interface GridView extends Omit<ListView, 'type' | 'detail'> {
209
+ type: 'grid';
210
+ columns?: number;
211
+ /** Aspect ratio of each cell, e.g. `"1"`, `"16/9"`. Default `"1"`. */
212
+ aspectRatio?: string;
213
+ /** How images fill their cell. */
214
+ fit?: 'cover' | 'contain';
215
+ }
216
+ export interface MetadataEntry {
217
+ label: string;
218
+ value?: string;
219
+ icon?: Icon;
220
+ href?: string;
221
+ tag?: string | {
222
+ value: string;
223
+ color?: Color;
224
+ };
225
+ }
226
+ export interface DetailView extends BaseView {
227
+ type: 'detail';
228
+ /** Markdown. Pass an async iterable (e.g. an AI stream) to stream text in. */
229
+ markdown: string | AsyncIterable<string> | (() => Awaitable<string | AsyncIterable<string>>);
230
+ metadata?: MetadataEntry[];
231
+ }
232
+ export interface FormField {
233
+ name: string;
234
+ label?: string;
235
+ type?: 'text' | 'textarea' | 'password' | 'number' | 'email' | 'url' | 'checkbox' | 'select' | 'date';
236
+ placeholder?: string;
237
+ description?: string;
238
+ required?: boolean;
239
+ defaultValue?: string | number | boolean;
240
+ options?: {
241
+ title: string;
242
+ value: string;
243
+ }[];
244
+ /** Return an error message to block submission. */
245
+ validate?: (value: any, values: Record<string, any>) => string | undefined | void;
246
+ }
247
+ export interface FormView extends BaseView {
248
+ type: 'form';
249
+ fields: FormField[];
250
+ submitLabel?: string;
251
+ onSubmit(values: Record<string, any>, ctx: Context): Awaitable<RunResult>;
252
+ }
253
+ export interface ChatView extends BaseView {
254
+ type: 'chat';
255
+ /** First user message, sent immediately. */
256
+ prompt?: string;
257
+ /** Override the system prompt. */
258
+ system?: string;
259
+ /** Let the model run app commands and tools. Default `true`. */
260
+ tools?: boolean;
261
+ }
262
+ export type View = ListView | GridView | DetailView | FormView | ChatView;
263
+ /** A dynamic provider of root search results (records from your API, docs, …). */
264
+ export interface Source {
265
+ id: string;
266
+ /** Section heading for results. */
267
+ title?: string;
268
+ search(args: LoadArgs): Awaitable<Item[]>;
269
+ /** Minimum query length before `search` runs. Default 1. */
270
+ minQueryLength?: number;
271
+ /** Debounce in ms. Default 150. */
272
+ debounce?: number;
273
+ /** Maximum results shown. Default 8. */
274
+ limit?: number;
275
+ /** Re-rank returned items with the local fuzzy matcher. Default `false`. */
276
+ filter?: boolean;
277
+ /** Show results above (`"top"`) or below (`"bottom"`, default) matching commands. */
278
+ position?: 'top' | 'bottom';
279
+ }
280
+ export interface Preference {
281
+ name: string;
282
+ title: string;
283
+ description?: string;
284
+ type: 'text' | 'password' | 'checkbox' | 'select' | 'number';
285
+ required?: boolean;
286
+ default?: string | number | boolean;
287
+ placeholder?: string;
288
+ options?: {
289
+ title: string;
290
+ value: string;
291
+ }[];
292
+ }
293
+ export interface ExtensionCommand extends Omit<Item, 'id'> {
294
+ /** Unique within the extension. */
295
+ name: string;
296
+ }
297
+ /** A function the AI model may call. */
298
+ export interface Tool<Args = any> {
299
+ name: string;
300
+ description: string;
301
+ /** JSON schema for the arguments object. */
302
+ parameters?: JSONSchema;
303
+ /** Ask the user before running. */
304
+ confirm?: boolean | ((args: Args) => string);
305
+ run(args: Args, ctx: Context): Awaitable<unknown>;
306
+ }
307
+ export type JSONSchema = {
308
+ type?: string | string[];
309
+ properties?: Record<string, JSONSchema>;
310
+ required?: string[];
311
+ items?: JSONSchema;
312
+ enum?: unknown[];
313
+ description?: string;
314
+ [key: string]: unknown;
315
+ };
316
+ export interface Extension {
317
+ /** Unique id, e.g. `"github"`. */
318
+ name: string;
319
+ title: string;
320
+ description?: string;
321
+ icon?: Icon;
322
+ author?: string;
323
+ version?: string;
324
+ /** Settings the extension needs. Missing required values are asked for on first run. */
325
+ preferences?: Preference[];
326
+ commands?: ExtensionCommand[];
327
+ sources?: Source[];
328
+ tools?: Tool[];
329
+ /** Called once when the extension is installed. Return a cleanup function. */
330
+ setup?(ctx: ExtensionSetupContext): void | (() => void);
331
+ }
332
+ export interface ExtensionSetupContext {
333
+ bar: QikbarInstance;
334
+ preferences: Record<string, any>;
335
+ storage: ScopedStorage;
336
+ }
337
+ export interface AIToolCall {
338
+ id: string;
339
+ name: string;
340
+ args: Record<string, unknown>;
341
+ /** Set when the model produced arguments that could not be parsed. The call is not executed. */
342
+ error?: string;
343
+ }
344
+ export interface AIMessage {
345
+ role: 'user' | 'assistant' | 'tool';
346
+ content: string;
347
+ toolCalls?: AIToolCall[];
348
+ /** For `role: 'tool'`. */
349
+ toolCallId?: string;
350
+ toolName?: string;
351
+ isError?: boolean;
352
+ /** Provider-native payload, replayed verbatim on the next request (e.g. thinking blocks). */
353
+ raw?: {
354
+ provider: string;
355
+ data: unknown;
356
+ };
357
+ }
358
+ export interface AIToolDefinition {
359
+ name: string;
360
+ description: string;
361
+ parameters: JSONSchema;
362
+ }
363
+ export interface AIRequest {
364
+ messages: AIMessage[];
365
+ system?: string;
366
+ tools?: AIToolDefinition[];
367
+ signal?: AbortSignal;
368
+ maxTokens?: number;
369
+ }
370
+ export type AIEvent = {
371
+ type: 'text';
372
+ text: string;
373
+ } | {
374
+ type: 'tool_call';
375
+ call: AIToolCall;
376
+ } | {
377
+ type: 'done';
378
+ message: AIMessage;
379
+ stopReason?: string;
380
+ } | {
381
+ type: 'error';
382
+ error: string;
383
+ };
384
+ /** Implement this to plug in any model. */
385
+ export interface AIProvider {
386
+ readonly id: string;
387
+ readonly model?: string;
388
+ /** Whether the provider supports tool calling. Default true. */
389
+ readonly tools?: boolean;
390
+ stream(request: AIRequest): AsyncIterable<AIEvent>;
391
+ }
392
+ export interface AIClient {
393
+ readonly provider: AIProvider;
394
+ /** Ask a one-shot question and get the full answer. */
395
+ ask(prompt: string, options?: {
396
+ system?: string;
397
+ signal?: AbortSignal;
398
+ }): Promise<string>;
399
+ /** Ask a one-shot question and stream the answer. */
400
+ stream(prompt: string, options?: {
401
+ system?: string;
402
+ signal?: AbortSignal;
403
+ }): AsyncIterable<string>;
404
+ }
405
+ export interface StorageAdapter {
406
+ getItem(key: string): string | null;
407
+ setItem(key: string, value: string): void;
408
+ removeItem(key: string): void;
409
+ }
410
+ export interface ScopedStorage {
411
+ get<T = unknown>(key: string): T | undefined;
412
+ set(key: string, value: unknown): void;
413
+ remove(key: string): void;
414
+ }
415
+ export interface ThemeVars {
416
+ font?: string;
417
+ fontMono?: string;
418
+ fontSize?: string;
419
+ bg?: string;
420
+ bgElevated?: string;
421
+ fg?: string;
422
+ fgMuted?: string;
423
+ fgSubtle?: string;
424
+ border?: string;
425
+ selection?: string;
426
+ selectionFg?: string;
427
+ hover?: string;
428
+ accent?: string;
429
+ accentFg?: string;
430
+ highlight?: string;
431
+ overlay?: string;
432
+ backdropBlur?: string;
433
+ shadow?: string;
434
+ radius?: string;
435
+ radiusItem?: string;
436
+ width?: string;
437
+ listHeight?: string;
438
+ rowHeight?: string;
439
+ sectionHeight?: string;
440
+ inputHeight?: string;
441
+ inputFontSize?: string;
442
+ top?: string;
443
+ kbdBg?: string;
444
+ kbdFg?: string;
445
+ danger?: string;
446
+ success?: string;
447
+ warning?: string;
448
+ /** Any other custom property, without the `--qb-` prefix. */
449
+ [key: string]: string | undefined;
450
+ }
451
+ export type ThemePresetName = 'light' | 'dark' | 'raycast' | 'linear' | 'vercel' | 'github' | 'nord' | 'dracula' | 'catppuccin' | 'tokyo-night' | 'rose-pine' | 'solarized' | 'midnight' | 'paper';
452
+ export interface ThemeConfig {
453
+ /** Preset to start from. */
454
+ preset?: ThemePresetName;
455
+ /** Variable overrides for both appearances. */
456
+ vars?: ThemeVars;
457
+ /** Overrides for light appearance. */
458
+ light?: ThemeVars;
459
+ /** Overrides for dark appearance. */
460
+ dark?: ThemeVars;
461
+ }
462
+ export type Appearance = 'light' | 'dark' | 'auto' | (() => 'light' | 'dark');
463
+ export type ClassNameSlot = 'root' | 'overlay' | 'dialog' | 'header' | 'input' | 'list' | 'section' | 'item' | 'footer' | 'actions' | 'detail' | 'form' | 'grid' | 'chat' | 'toast';
464
+ export interface Route {
465
+ path: string;
466
+ title: string;
467
+ subtitle?: string;
468
+ icon?: Icon;
469
+ keywords?: string[];
470
+ section?: string;
471
+ shortcut?: string;
472
+ }
473
+ export type Navigate = (href: string, options: {
474
+ newTab: boolean;
475
+ }) => void;
476
+ export interface QikbarConfig {
477
+ /** Commands shown at the root. */
478
+ commands?: Command[];
479
+ /** Routes in your app; each becomes a "go to" command. */
480
+ routes?: Route[];
481
+ /** Dynamic search providers. */
482
+ sources?: Source[];
483
+ /** Installed extensions. */
484
+ extensions?: (Extension | [Extension, Record<string, any>])[];
485
+ /** Items shown at the bottom when the query has no good matches. `{query}` is replaced in titles. */
486
+ fallbacks?: Item[];
487
+ /** Your router's navigate function. Defaults to clicking a matching link (works with most frameworks). */
488
+ navigate?: Navigate;
489
+ /** Hotkey that toggles the bar. Default `"mod+k"`. Set `false` to disable. */
490
+ hotkey?: string | string[] | false;
491
+ /** Hotkey that opens the action panel for the selected item. Default `"mod+."`. */
492
+ actionsHotkey?: string;
493
+ /** Enable items' global `shortcut`s while the bar is closed. Default true. */
494
+ shortcuts?: boolean;
495
+ placeholder?: string;
496
+ /** Show "Recent" items at the top when the query is empty. Default true. */
497
+ recents?: boolean | number;
498
+ /** Index links in your page automatically (`nav a`, `[data-qikbar]`). */
499
+ autoIndex?: boolean | AutoIndexOptions;
500
+ /** AI provider. Unlocks Ask AI, natural-language commands and `ctx.ai`. */
501
+ ai?: AIProvider | AIOptions;
502
+ /** Functions the AI may call, in addition to running commands. */
503
+ tools?: Tool[];
504
+ theme?: ThemePresetName | ThemeConfig;
505
+ appearance?: Appearance;
506
+ /** Extra classes per UI slot (works great with Tailwind). */
507
+ classNames?: Partial<Record<ClassNameSlot, string>>;
508
+ /** Don't inject default styles. */
509
+ unstyled?: boolean;
510
+ /** CSP nonce for the injected `<style>` tag. */
511
+ nonce?: string;
512
+ /** Render into this element instead of a modal (always open). */
513
+ inline?: HTMLElement | string;
514
+ /** Where the modal is mounted. Default `document.body`. */
515
+ container?: HTMLElement;
516
+ /** Namespace for persistent storage. Default `"qikbar"`. */
517
+ namespace?: string;
518
+ storage?: StorageAdapter;
519
+ /** Text direction. */
520
+ dir?: 'ltr' | 'rtl';
521
+ /** Show the "Powered by qikbar" footer mark. Default false. */
522
+ branding?: boolean;
523
+ /** Footer hint shown at the left when idle. */
524
+ footer?: string;
525
+ onOpen?: () => void;
526
+ onClose?: () => void;
527
+ /** Called whenever an item or action runs. Useful for analytics. */
528
+ onRun?: (item: Item, action: Action) => void;
529
+ }
530
+ export interface AutoIndexOptions {
531
+ /** CSS selector for links to index. Default `"nav a[href], header a[href], aside a[href], [data-qikbar-index] a[href]"`. */
532
+ links?: string | false;
533
+ /** Index elements with a `data-qikbar` attribute as commands that click them. Default true. */
534
+ elements?: boolean;
535
+ /** Section title for indexed links. Default `"Pages"`. */
536
+ section?: string;
537
+ }
538
+ export interface AIOptions {
539
+ provider: AIProvider;
540
+ /** System prompt prepended to every conversation. */
541
+ system?: string;
542
+ /** Show the "Ask AI" fallback when the query has text. Default true. */
543
+ fallback?: boolean;
544
+ /** Let the AI run commands/navigate/tools from chat. Default true. */
545
+ tools?: boolean;
546
+ /** Name shown in the UI. Default "AI". */
547
+ name?: string;
548
+ /** Max tool-calling steps per message. Default 6. */
549
+ maxSteps?: number;
550
+ /** Example prompts shown in an empty chat. */
551
+ suggestions?: string[];
552
+ /** Let the AI read the current page's text when asked about it. Default true. */
553
+ pageContext?: boolean;
554
+ }
555
+ export interface QikbarState {
556
+ open: boolean;
557
+ query: string;
558
+ depth: number;
559
+ loading: boolean;
560
+ }
561
+ export interface QikbarEvents {
562
+ open: void;
563
+ close: void;
564
+ change: QikbarState;
565
+ run: {
566
+ item: Item;
567
+ action: Action;
568
+ };
569
+ }
570
+ export interface QikbarInstance {
571
+ open(options?: {
572
+ query?: string;
573
+ view?: View;
574
+ }): void;
575
+ close(): void;
576
+ toggle(): void;
577
+ readonly isOpen: boolean;
578
+ /** Register commands. Returns an unregister function. */
579
+ register(commands: Command | Command[]): () => void;
580
+ /** Add a source. Returns a remove function. */
581
+ addSource(source: Source): () => void;
582
+ /** Install an extension. Returns an uninstall function. */
583
+ use(extension: Extension, preferences?: Record<string, any>): () => void;
584
+ /** Update configuration. */
585
+ configure(config: Partial<QikbarConfig>): void;
586
+ push(view: View): void;
587
+ pop(): void;
588
+ setQuery(query: string): void;
589
+ readonly query: string;
590
+ toast(options: ToastOptions | string): ToastHandle;
591
+ /** Run an AI chat with an optional prompt. */
592
+ ask(prompt?: string): void;
593
+ readonly ai: AIClient | undefined;
594
+ /** Every root command currently registered (after `when` filtering). */
595
+ commands(): Item[];
596
+ on<K extends keyof QikbarEvents>(event: K, handler: (payload: QikbarEvents[K]) => void): () => void;
597
+ /** Load the UI ahead of time (it otherwise loads when the browser is idle). */
598
+ preload(): Promise<void>;
599
+ destroy(): void;
600
+ }
601
+ export {};
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Built-in extensions. Each is a plain `Extension` object — read the source to
3
+ * learn the extension API, or copy one as a starting point for your own.
4
+ */
5
+ import type { Extension } from '../core/types.js';
6
+ export { convert, evaluate, formatNumber } from './math.js';
7
+ /** Type math or conversions straight into the bar: `12 * (3 + 4)`, `15% of 80`, `5 km in mi`. */
8
+ export declare function calculator(): Extension;
9
+ export type ThemeMode = 'light' | 'dark' | 'system';
10
+ export interface ThemeSwitcherOptions {
11
+ /** Apply a theme. Default: toggles the `dark` class and `color-scheme` on `<html>` and saves to localStorage. */
12
+ set?: (mode: ThemeMode) => void;
13
+ /** Shortcut for "Toggle Theme". Default `"mod+shift+l"`. */
14
+ shortcut?: string | false;
15
+ storageKey?: string;
16
+ }
17
+ /** Light / dark / system theme commands. */
18
+ export declare function themeSwitcher(options?: ThemeSwitcherOptions): Extension;
19
+ export interface PageOptions {
20
+ /** Index headings on the current page so users can jump to them. Default `"h1[id], h2[id], h3[id]"`. Set `false` to disable. */
21
+ headings?: string | false;
22
+ }
23
+ /** Browser and page utilities: back/forward, copy URL, scroll, print, share, jump to heading. */
24
+ export declare function page(options?: PageOptions): Extension;
25
+ /** AI commands that work on the current page or selected text. Requires `ai` to be configured. */
26
+ export declare function aiActions(): Extension;
27
+ /** A "Keyboard Shortcuts" command listing every shortcut in your app. */
28
+ export declare function shortcuts(): Extension;
29
+ /** Format a shortcut for display outside the bar, e.g. in a button: `"⌘K"`. */
30
+ export declare function shortcutLabel(hotkey: string): string;
@@ -0,0 +1,14 @@
1
+ /**
2
+ * A safe arithmetic evaluator (no `eval`). Supports + - * / % ^ **, parentheses,
3
+ * implicit multiplication ("2pi", "3(4+1)"), percentages ("15% of 80", "200 + 10%"),
4
+ * constants, common functions and unit conversions ("5 km in miles").
5
+ */
6
+ export declare function evaluate(expression: string): number;
7
+ /** "5 km in miles" → { value, unit } or undefined. */
8
+ export declare function convert(input: string): {
9
+ value: number;
10
+ unit: string;
11
+ } | undefined;
12
+ export declare function formatNumber(v: number): string;
13
+ /** Heuristic: does the query look like something to calculate? */
14
+ export declare function looksLikeMath(q: string): boolean;