 # Script Kit 2.0 Release Candidate

Download for your platform from the releases page:
https://github.com/johnlindquist/kitapp/releases/tag/v1.99.82

## New Main Menu

The main menu has been re-designed and optimized for your keyboard-centric workflows.

<img width="827" alt="CleanShot 2023-10-27 at 07 47 09@2x" src="https://github.com/johnlindquist/kit/assets/36073/60b9d227-d0a1-4cf0-ae2a-bede13fba9ef">

## New Custom OSX Window

Prompts like `editor` and `term` which use `ignoreBlur` will now convert the window into an "app" window which can be accessed by `cmd+tab`, is pinned when switching spaces, and shows up in Mission Control. This is also forward-looking to v3 which I'll talk about more in the future...

## Keywords
Borrowed directly from Alfred, keywords allow you to trigger a script by typing a keyword followed by a space.

A keyword can be a single character or a word. For example, `c` for `clipboard`.

### Built-in Keywords
- `s` - Displays Snippets from your Snippets Directory
- `c` - Displays Clipboard History
- `f` - Find script by searching script contents
- `kit` - Access kit settings
- `kenv` - Access kenv options
- `npm` - Add/remove npm packages
- `spell` - List spelling suggestions for the input
 
 And many others. To see them all, type `keyword` into the Script Kit prompt.

 To create a custom keyword for your own scripts, add:

 ```
 // Keyword: mycustomkeyword
 ```

 If the first prompt is an `await arg()`, it will display the list in the main menu. Otherwise, it will jump to the next prompt.

 Also, if the first prompt is a static list and you shave off the few milliseconds required to load the list from your script, you can cache the list (after the first run) by adding:

 ```
 // Cache: true
 ```

Use caching sparingly, as it's only useful for `// Keyword` and `// Shortcut` where the first prompt is an `arg` with a static list.

## Pass Main Menu Input to a Script

```
// Pass: true
```

The `Pass` metadata allows you to type into the main menu without your script being filtered out of the list. Once you select the script, the input you've typed will be "passed" into the script. You can access the "passed" input using `flag?.pass`. For example, if you want to pass the main menu input to the input of you first arg:

```
// Name: Pass Demo
// Pass: true

import "@johnlindquist/kit"

await arg({
  input: flag?.pass || "",
})
```

### Pass "postfix"

Image you want to type: "How many moons does Jupiter have?" and have the "?" automatically trigger a script that reaches out to an AI service. You can do this by adding a "postfix" to the `Pass` metadata.

```
// Pass: ?
```

This will automatically trigger the script when you type a "?" at the end in the main menu and the entire input will be passed to the script as `flag?.pass`.

## Multi-select Prompt `await select()`

<img width="833" alt="CleanShot 2023-10-27 at 15 26 56@2x" src="https://github.com/johnlindquist/kit/assets/36073/9420d7a8-096c-468b-b98c-a9f70b48569b">

```js
let arrayOfChoices = await select("Pick one or more", ["one", "two", "three"])
```

Probably the most requested feature, Script Kit now has a `select` prompt which allows you to pick multiple choices.

## Themes Per Light/Dark Mode

You can now customize which theme will be active for both light and dark more or use the same theme for both.

## Snippets Directory

In your ~/.kenv/snippets directory, create .txt files you want to use as snippets. For example:
1. Create `~/.kenv/snippets/lorem.txt`
2. Add the following text to the file:
```
// Name: Lorem Ipsum
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
```

The "Lorem Ipsum" snippet will now appear in the Snippets menu using the `s` keyword. Select the snippet will paste it into the current application.

Adding Snippet metadata will allow you to invoke the snippet anywhere on your system. It's a best practice to use a "postfix", such as ",,", to avoid triggering the snippet when you don't want to.
```
// Snippet: lorem,,
```

### Snippet Creator

<img width="829" alt="CleanShot 2023-10-27 at 01 02 25@2x" src="https://github.com/johnlindquist/kit/assets/36073/a32d5e12-8ff2-441c-8edf-cfdfe3b1ab0d">

Typing `ns ` from the main menu will launch the quick snippet creator. There's a helpful guide there that will show all the available options. Just to list a few:

- Tab stops: $0, $1, $2, $3
- Dropdown list: ${|apple,banana,cherry|}
- Current selection: $SELECTION
- Clipboard content: $CLIPBOARD

and many more...

If you need more advanced scenarios, for example clipboard history:

```js
let history = await getClipboardHistory()
let text = await arg("Pick an item from your history", history.map(item => item.value)

let result = await template(`Hello $0,

${text}
`)

await writeFile(home("example.txt"), result)
```

## Actions

The new `actions` array makes it much easier to assign shortcuts and behaviors when you have a choice selected. You can access the actions menu by pressing `right`on the keyboard, then quickly search to execute the action you want to take with the currently focused choice:

```js
// Name: Actions Example

import { Action } from "@johnlindquist/kit"

// Using a "flag" determines where to do to custom logic: After the prompt or in the action
// Also, "flags" are supported when running the script in the terminal with `--js`
let actions: Action[] = [
  {
    shortcut: `${cmd}+t`,
    name: "Append .ts",
    visible: true, // Display shortcut in the prompt
    onAction: async (input, state) => {
      // Since we're not using a "flag", we can do custom logic here
      submit(`${state.focused?.name}.ts`)
    },
  },
  {
    name: "Append .js",
    flag: "js", // Set `global.flag.js` to true when selecting the action
  },
]

let result = await arg("Pick a number", ["one", "two", "three"], actions)

if (flag.js) {
  result = `${result}.js`
}

inspect(result)
```

## Previews on All Prompts

You can build-out helpful previews on the right side for all prompts now (see the Snippet Creator above for a great example). This is especially useful for prompts like `editor`, `drop`, and `term` where you may need reminders on what the script is doing or steps you want to guide the user through.

```js
await editor({
  value: `Book Outline`,
  preview: md(`# Requirements
- Cover Major Characters
- Address the theme
- Have a beginning, middle, and end  
  `),
})
```


## Move kenv to a Different Directory

Type `kit move` into the main prompt to move your kenv directory to a different location. This is useful if you want to keep your scripts in dotfiles or other setup.


## onClick and onKeydown Globals
- Global event handlers for click and type events.

## Custom TypeScript Loader

The new custom loader eliminates the need to watch .ts files for changes (which caused many issues from a long-running app). We now have a customized loader that can run any TypeScript file instantly.

An awesome benefit of this is you can create a script anywhere on your system, such as `~/Desktop/my-script.ts` (or js if you prefer) and run it from script runner: `~/.kit/bin/kit ~/Desktop/my-script.ts`.

> Note: Your IDE won't recognize the `import` statements since it's not in a project, but the script will run just fine.

If we get enough requests, we will allow you to run the scripts from the built-in file browser through the app as well.


## Watch Scripts for npm Install

As you're writing your scripts in your favorite editor, Kit.app will detect if you've added a new npm package and automatically prompt you to install it using the Kit.app built-in terminal.


## Road to v2

The plan is to release v2 in mid-December. I'll be focusing on updating documentation, guides, tips, and tricks to finally help everyone get a more complete grasp of what Script Kit is capable of. There are a few more APIs which haven't been announced which will be included as well.


## Questions?

Please ask below. We're always happy to help figure out better workflows to optimize your day. Happy scripting!

\- John