### Installation and Setup

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Instructions on how to install the SketchyBar Lua module and configure Lua to find it.

```APIDOC
## Installation

Install and update the module with the following command:
```bash
(git clone https://github.com/FelixKratz/SbarLua.git /tmp/SbarLua && cd /tmp/SbarLua/ && make install && rm -rf /tmp/SbarLua/)
```

## Lua Path Configuration

For Lua to find the module, add its path to `package.cpath`:
```lua
package.cpath = package.cpath .. ";/Users/" .. os.getenv("USER") .. "/.local/share/sketchybar_lua/?.so"
```

## Requiring the Module

Once installed and configured, require the module in your Lua script:
```lua
local sbar = require("sketchybar")
```
```

--------------------------------

### Installation and Module Setup

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Instructions for installing the SbarLua module and setting up your Lua configuration script.

```APIDOC
## Installation

Install and build the Lua module from source.

```bash
git clone https://github.com/FelixKratz/SbarLua.git /tmp/SbarLua && cd /tmp/SbarLua/ && make install && rm -rf /tmp/SbarLua/
```

## Module Setup

Configure the Lua path and require the sketchybar module in your configuration script.

```lua
#!/usr/bin/env lua

-- Add the sketchybar module to the package cpath
package.cpath = package.cpath .. ";/Users/" .. os.getenv("USER") .. "/.local/share/sketchybar_lua/?.so"

-- Require the sketchybar module
sbar = require("sketchybar")

-- Bundle configuration into a single message for faster startup
sbar.begin_config()
-- ... your configuration here ...
sbar.hotload(true)
sbar.end_config()

-- Run the event loop (required for callback functions)
sbar.event_loop()
```
```

--------------------------------

### Install SketchyBar Lua Module

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Installs and builds the SketchyBar Lua module from source. Ensure you have git and make installed.

```bash
(git clone https://github.com/FelixKratz/SbarLua.git /tmp/SbarLua && cd /tmp/SbarLua/ && make install && rm -rf /tmp/SbarLua/)
```

--------------------------------

### Transaction Batching for Configuration

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Bundle multiple commands into a single message using `sbar.begin_config()` and `sbar.end_config()` for improved startup performance. This is ideal for initial setup or complex configuration changes.

```lua
sbar.begin_config()

-- All these commands are batched
sbar.bar({ height = 40 })
sbar.default({ icon = { color = 0xffffffff } })
local item1 = sbar.add("item", { label = "Item 1" })
local item2 = sbar.add("item", { label = "Item 2" })

sbar.end_config()  -- Commands sent as single batch
```

--------------------------------

### Install SbarLua from Source

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Clone the repository, build the Lua module, and install it. This command also removes the cloned directory after installation.

```bash
git clone https://github.com/FelixKratz/SbarLua.git /tmp/SbarLua && cd /tmp/SbarLua/ && make install && rm -rf /tmp/SbarLua/
```

--------------------------------

### Configure Lua Path and Require Sketchybar Module

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Sets up the Lua package path to include the Sketchybar module and requires it. It also demonstrates starting a configuration transaction and enabling hotloading.

```lua
#!/usr/bin/env lua

-- Add the sketchybar module to the package cpath
package.cpath = package.cpath .. ";/Users/" .. os.getenv("USER") .. "/.local/share/sketchybar_lua/?.so"

-- Require the sketchybar module
sbar = require("sketchybar")

-- Bundle configuration into a single message for faster startup
sbar.begin_config()
-- ... your configuration here ...
sbar.hotload(true)
sbar.end_config()

-- Run the event loop (required for callback functions)
sbar.event_loop()
```

--------------------------------

### Complete SketchyBar Lua Configuration

Source: https://context7.com/felixkratz/sbarlua/llms.txt

This snippet shows a full SketchyBar configuration using Lua. It includes setting up the bar, default item styles, creating dynamic spaces with click and space change subscriptions, and a battery indicator. Ensure the `sketchybar_lua` module is accessible via `package.cpath`.

```lua
#!/usr/bin/env lua

package.cpath = package.cpath .. ";/Users/" .. os.getenv("USER") .. "/.local/share/sketchybar_lua/?.so"
sbar = require("sketchybar")

sbar.begin_config()

-- Configure bar appearance
sbar.bar({
  height = 40,
  color = 0xff1e1e2e,
  shadow = true,
  sticky = true,
  padding_right = 10,
  padding_left = 10,
})

-- Set default item properties
sbar.default({
  icon = {
    font = { family = "SF Pro", style = "Bold", size = 14.0 },
    color = 0xffffffff,
    padding_left = 4,
    padding_right = 4,
  },
  label = {
    font = { family = "SF Pro", style = "Semibold", size = 13.0 },
    color = 0xffffffff,
    padding_left = 4,
    padding_right = 4,
  },
})

-- Add spaces
local spaces = {}
for i = 1, 5 do
  local space = sbar.add("space", {
    associated_space = i,
    icon = { string = tostring(i) },
  })
  spaces[i] = space.name

  space:subscribe("space_change", function(env)
    sbar.set(env.NAME, {
      icon = { highlight = env.SELECTED }
    })
  end)

  space:subscribe("mouse.clicked", function(env)
    sbar.exec("yabai -m space --focus " .. env.SID)
  end)
end

-- Add bracket around spaces
sbar.add("bracket", spaces, {
  background = { color = 0xff363a4f, corner_radius = 9 }
})

-- Add battery indicator
local battery = sbar.add("item", {
  position = "right",
  update_freq = 120,
})

battery:subscribe({"routine", "power_source_change"}, function()
  sbar.exec("pmset -g batt", function(batt_info)
    local icon = "􀛨"
    if string.find(batt_info, 'AC Power') then
      icon = "􀢋"
    end
    battery:set({ icon = icon })
  end)
end)

sbar.hotload(true)
sbar.end_config()
sbar.event_loop()

```

--------------------------------

### Transaction Batching (sbar.begin_config / sbar.end_config)

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Bundle multiple commands into a single message for improved startup performance. Ensures atomic updates.

```APIDOC
## sbar.begin_config / sbar.end_config - Transaction Batching

Bundle multiple commands into a single message for improved startup performance.

### Example: Batching configuration commands
```lua
sbar.begin_config()

-- All these commands are batched
sbar.bar({ height = 40 })
sbar.default({ icon = { color = 0xffffffff } })
local item1 = sbar.add("item", { label = "Item 1" })
local item2 = sbar.add("item", { label = "Item 2" })

sbar.end_config()  -- Commands sent as single batch
```
```

--------------------------------

### Asynchronous Command Execution

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Demonstrates how to execute shell commands asynchronously using `sbar.exec` to avoid blocking the Lua event handler.

```APIDOC
## Asynchronous Execution

Avoid `os.execute` or `io.popen`. Use `sbar.exec` for non-blocking command execution.

### Basic Usage
```lua
sbar.exec(<command>)
```

### With Completion Handler

Optionally, provide a Lua function to handle the command's result.
```lua
sbar.exec(<command>, [Optional: <lua_function>])
```

**Example:**
```lua
sbar.exec("sleep 5 && echo TEST", function(result, exit_code) print(result) end)
```

The `result` will be parsed into a Lua table if it has a JSON structure.
```

--------------------------------

### Configure Global Bar Appearance Properties

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Sets global properties for the SketchyBar, such as height, colors, padding, and blur effects. Requires a 'colors' module to be loaded.

```lua
local colors = require("colors")

sbar.bar({
  height = 40,
  color = colors.bar.bg,
  border_color = colors.bar.border,
  shadow = true,
  sticky = true,
  padding_right = 10,
  padding_left = 10,
  blur_radius = 20,
  topmost = "window",
})
```

--------------------------------

### Async Command Execution (sbar.exec)

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Execute shell commands asynchronously without blocking the event loop. JSON output is automatically parsed into Lua tables.

```APIDOC
## sbar.exec - Async Command Execution

Execute shell commands asynchronously without blocking the event loop. JSON output is automatically parsed.

### Example: Simple async execution (fire and forget)
```lua
sbar.exec("yabai -m space --focus 1")
```

### Example: With callback for result handling
```lua
sbar.exec("pmset -g batt", function(result, exit_code)
  local found, _, charge = result:find("(%d+)%%")
  if found then
    battery:set({ label = charge .. "%" })
  end
end)
```

### Example: Execute with JSON output (auto-parsed to Lua table)
```lua
sbar.exec("yabai -m query --spaces", function(spaces, exit_code)
  -- 'spaces' is already a Lua table
  for i, space in ipairs(spaces) do
    print("Space " .. i .. " has " .. #space.windows .. " windows")
  end
end)
```

### Example: Volume control via osascript
```lua
volume_slider:subscribe("mouse.clicked", function(env)
  sbar.exec("osascript -e 'set volume output volume " .. env["PERCENTAGE"] .. "'")
end)
```
```

--------------------------------

### Configure Default Properties

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Sets default properties for SketchyBar elements.

```lua
sbar.default(<property_table>)
```

--------------------------------

### Animations (sbar.animate)

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Wrap set/bar commands in animations with specified curve and duration. Useful for smooth visual transitions.

```APIDOC
## sbar.animate - Animations

Wrap set/bar commands in animations with specified curve and duration.

### Example: Animate slider width
```lua
local function animate_slider_width(width)
  sbar.animate("tanh", 30.0, function()
    volume_slider:set({ slider = { width = width }})
  end)
end
```

### Example: Toggle volume slider visibility on click
```lua
volume_icon:subscribe("mouse.clicked", function()
  if tonumber(volume_slider:query().slider.width) > 0 then
    animate_slider_width(0)
  else
    animate_slider_width(100)
  end
end)
```

### Example: Animate multiple properties
```lua
sbar.animate("sin", 20, function()
  my_item:set({
    icon = { color = 0xffed8796 },
    background = { color = 0xff363a4f }
  })
end)
```
```

--------------------------------

### Space Selection Change Handling

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Subscribe to space selection changes to dynamically update item appearance based on whether the space is selected or not. This allows for visual feedback on space selection.

```lua
-- Space selection change
space:subscribe("space_change", function(env)
  local color = env.SELECTED == "true" and 0xffffffff or 0xff494d64
  sbar.set(env.NAME, {
    icon = { highlight = env.SELECTED },
    label = { highlight = env.SELECTED },
    background = { border_color = color }
  })
end)
```

--------------------------------

### Event Subscriptions (item:subscribe)

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Subscribe items to SketchyBar events and define callback functions that receive environment variables. Supports single or multiple event subscriptions.

```APIDOC
## item:subscribe - Event Subscriptions

Subscribe items to SketchyBar events with callback functions. Callbacks receive environment variables.

### Example: Subscribe to a single event
```lua
front_app:subscribe("front_app_switched", function(env)
  front_app:set({
    label = { string = env.INFO }
  })
end)
```

### Example: Subscribe to multiple events
```lua
battery:subscribe({"routine", "power_source_change", "system_woke"}, function(env)
  -- Update battery status
  sbar.exec("pmset -g batt", function(batt_info)
    local icon = "􀛨"
    if string.find(batt_info, 'AC Power') then
      icon = "􀢋"
    end
    battery:set({ icon = icon })
  end)
end)
```

### Example: Mouse click handling
```lua
space:subscribe("mouse.clicked", function(env)
  if env.BUTTON == "right" then
    sbar.exec("yabai -m space --destroy " .. env.SID)
  else
    sbar.exec("yabai -m space --focus " .. env.SID)
  end
end)
```

### Example: Space selection change
```lua
space:subscribe("space_change", function(env)
  local color = env.SELECTED == "true" and 0xffffffff or 0xff494d64
  sbar.set(env.NAME, {
    icon = { highlight = env.SELECTED },
    label = { highlight = env.SELECTED },
    background = { border_color = color }
  })
end)
```
```

--------------------------------

### Targeting Multiple Sketchybar Instances

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Use this method to interact with a specific sketchybar instance when running multiple. Provide the instance name after requiring the module.

```bash
sbar = require("sketchybar")
sbar.set_bar_name("bottom_bar")
```

--------------------------------

### Default Domain API

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Configure default properties using the `sbar.default` function.

```APIDOC
## Default Properties

Set default properties for elements.

### Method
```lua
sbar.default(<property_table>)
```

### Parameters
- **property_table** (table) - A Lua table with key-value pairs for default properties.
```

--------------------------------

### sbar.bar - Bar Configuration API

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Configure global bar appearance properties including height, color, shadow, padding, and blur effects.

```APIDOC
## sbar.bar - Bar Configuration

Configure global bar appearance properties including height, color, shadow, padding, and blur effects.

```lua
local colors = require("colors")

sbar.bar({
  height = 40,
  color = colors.bar.bg,
  border_color = colors.bar.border,
  shadow = true,
  sticky = true,
  padding_right = 10,
  padding_left = 10,
  blur_radius = 20,
  topmost = "window",
})
```
```

--------------------------------

### Query Item Information

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Queries an item for its information, returning it as a Lua table. This allows direct access to item properties.

```lua
local info = item:query()
```

```lua
local left_padding = front_app:query().icon.padding_left
```

--------------------------------

### Add a Simple Item

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Adds a basic menu bar item with auto-generated name. Icon drawing is disabled, and the label font style and size are specified.

```lua
-- Add a simple item (name auto-generated)
local front_app = sbar.add("item", {
  icon = { drawing = false },
  label = {
    font = { style = "Black", size = 12.0 }
  }
})
```

--------------------------------

### Subscribe to Single Event

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Subscribe to a single event and define a callback function to handle it. The callback receives environment variables.

```lua
-- Subscribe to a single event
front_app:subscribe("front_app_switched", function(env)
  front_app:set({
    label = { string = env.INFO }
  })
end)
```

--------------------------------

### Add Domain API

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Add various elements like items, spaces, brackets, sliders, and events to the bar.

```APIDOC
## Add Elements

Add different types of elements to the bar.

### Item, Space, Alias
```lua
local item = sbar.add(<"item", "space", "alias">, <optional: name>, <property_table>)
```

### Bracket
```lua
local bracket = sbar.add("bracket", <optional: name>, <member_table>, <property_table>)
```

### Slider, Graph
```lua
local slider = sbar.add(<"slider", "graph">, <optional: name>, <width>, <property_table>)
```

### Event
```lua
local event = sbar.add("event", <name>, <optional: NSDistributedNotification>)
```

### Parameters
- **type** (string) - The type of element to add (e.g., "item", "space", "bracket", "slider", "graph", "event").
- **name** (string, optional) - An identifier for the element.
- **member_table** (table, for "bracket") - A list of members for the bracket.
- **width** (number, for "slider", "graph") - The width of the slider or graph.
- **property_table** (table) - Key-value pairs for element properties.
- **NSDistributedNotification** (string, optional, for "event") - The notification name.
```

--------------------------------

### Add a Slider with Width Parameter

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Adds a 'slider' item with a specified width. It configures the highlight color, background height, corner radius, and the appearance of the slider knob.

```lua
-- Add a slider with width parameter
local volume_slider = sbar.add("slider", 100, {
  position = "right",
  slider = {
    highlight_color = 0xff8aadf4,
    width = 0,
    background = {
      height = 6,
      corner_radius = 3,
      color = 0xff494d64,
    },
    knob = { string = "􀀁", drawing = false },
  },
})
```

--------------------------------

### Add a Bracket Grouping Multiple Items

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Creates a 'bracket' item to group multiple existing items (specified by their names). It configures the background color and border color for the bracket.

```lua
-- Add a bracket grouping multiple items
local spaces = {"space_1", "space_2", "space_3"}
sbar.add("bracket", spaces, {
  background = {
    color = 0xff363a4f,
    border_color = 0xff494d64
  }
})
```

--------------------------------

### Trigger Domain API

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Manually trigger a SketchyBar event.

```APIDOC
## Trigger Event

Manually trigger a SketchyBar event.

### Method
```lua
sbar.trigger(<event>, <optional: env_table>)
```

### Parameters
- **event** (string) - The name of the event to trigger.
- **env_table** (table, optional) - A table of environment variables to pass with the event.
```

--------------------------------

### Bar Domain API

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Configure global bar properties using the `sbar.bar` function.

```APIDOC
## Bar Configuration

Set global bar properties.

### Method
```lua
sbar.bar(<property_table>)
```

### Parameters
- **property_table** (table) - A Lua table containing key-value pairs for bar properties. Keys correspond to SketchyBar documentation properties, with dots replaced by sub-tables (e.g., `icon = { y_offset = 10, width = 50 }`).
```

--------------------------------

### Mouse Click Handling for Space

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Handle mouse clicks on a space item, differentiating between right and left clicks to perform different actions like destroying or focusing a space.

```lua
-- Mouse click handling
space:subscribe("mouse.clicked", function(env)
  if env.BUTTON == "right" then
    sbar.exec("yabai -m space --destroy " .. env.SID)
  else
    sbar.exec("yabai -m space --focus " .. env.SID)
  end
end)
```

--------------------------------

### Query Item State (item:query)

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Query the current state of an item, returning a Lua table with all its properties. Useful for conditional logic.

```APIDOC
## item:query - Query Item State

Query current item state, returns a Lua table with all properties.

### Example: Get slider width
```lua
local slider_width = volume_slider:query().slider.width
```

### Example: Get icon padding
```lua
local padding = front_app:query().icon.padding_left
```

### Example: Conditional logic based on current state
```lua
if tonumber(volume_slider:query().slider.width) > 0 then
  -- Slider is visible
  animate_slider_width(0)
else
  -- Slider is hidden
  animate_slider_width(100)
end
```
```

--------------------------------

### Enable Hot Reloading (sbar.hotload)

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Enable or disable configuration hot reloading when files change. Useful for development.

```APIDOC
## sbar.hotload - Enable Hot Reloading

Enable or disable configuration hot reloading when files change.

### Example: Enable hot reloading
```lua
sbar.hotload(true)   -- Enable hot reload
```

### Example: Disable hot reloading
```lua
sbar.hotload(false)  -- Disable hot reload
```
```

--------------------------------

### Subscribe Domain API

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Subscribe an element to SketchyBar events and define a callback function.

```APIDOC
## Subscribe to Events

Listen for SketchyBar events and execute a callback function.

### Method
```lua
item:subscribe(<event(s)>, <lua_function>)
```

### Parameters
- **event(s)** (string or table) - The event name(s) to subscribe to.
- **lua_function** (function) - The callback function to execute when the event occurs. It receives environment variables as an argument.

**Example:**
```lua
front_app:subscribe("front_app_switched", function(env)
  front_app:set({ label = { string = env.INFO } })
end)
```
```

--------------------------------

### Configure Lua CPath

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Appends the SketchyBar Lua module path to the Lua cpath. This allows Lua scripts to find the module.

```lua
package.cpath = package.cpath .. ";/Users/" .. os.getenv("USER") .. "/.local/share/sketchybar_lua/?.so"
```

--------------------------------

### Subscribe to SketchyBar Events

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Subscribes an item to SketchyBar events. The provided Lua function is called when an event occurs, receiving environment variables as an argument.

```lua
item:subscribe(<event(s)>, <lua_function>)
```

```lua
front_app:subscribe("front_app_switched", function(env)
  front_app:set({ label = { string = env.INFO } })
end)
```

--------------------------------

### Require SketchyBar Module

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Loads the SketchyBar Lua module, making its functions available for use in your Lua script.

```lua
local sbar = require("sketchybar")
```

--------------------------------

### Enable/Disable Hot Reloading

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Enable or disable configuration hot reloading using `sbar.hotload()`. This feature allows the configuration to update automatically when files change.

```lua
sbar.hotload(true)   -- Enable hot reload
```

```lua
sbar.hotload(false)  -- Disable hot reload
```

--------------------------------

### Animate Domain API

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Define animations for property changes.

```APIDOC
## Animate Properties

Define animations for property changes.

### Method
```lua
sbar.animate(<curve>, <duration>, <lua_function>)
```

### Parameters
- **curve** (string) - The animation curve type (e.g., "ease", "linear").
- **duration** (number) - The duration of the animation in seconds.
- **lua_function** (function) - A function containing the commands to be animated (e.g., `set` or `bar` commands).
```

--------------------------------

### Add a Custom Event

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Adds a custom event that can be triggered and subscribed to. This allows for custom event handling within SketchyBar.

```lua
-- Add a custom event
local my_event = sbar.add("event", "my_custom_event")
```

--------------------------------

### Set Multiple Bar Instances

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Target a different SketchyBar instance by name using `sbar.set_bar_name()`. All subsequent commands will apply to the specified bar instance.

```lua
sbar = require("sketchybar")
sbar.set_bar_name("bottom_bar")

-- All subsequent commands target "bottom_bar" instance
sbar.bar({ height = 30 })
```

--------------------------------

### Add a Named Item with Position

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Adds a menu bar item with a specific name ('my_calendar') and positions it to the right. It also configures icon padding, label width, alignment, and update frequency.

```lua
-- Add a named item with position
local calendar = sbar.add("item", "my_calendar", {
  position = "right",
  icon = { padding_right = 0 },
  label = { width = 45, align = "right" },
  update_freq = 15,
})
```

--------------------------------

### Subscribe to Multiple Events

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Subscribe to multiple events simultaneously with a single callback function. This is useful for grouping related event handlers.

```lua
-- Subscribe to multiple events
battery:subscribe({"routine", "power_source_change", "system_woke"}, function(env)
  -- Update battery status
  sbar.exec("pmset -g batt", function(batt_info)
    local icon = "􀛨"
    if string.find(batt_info, 'AC Power') then
      icon = "􀢋"
    end
    battery:set({ icon = icon })
  end)
end)
```

--------------------------------

### Trigger Custom Event

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Manually trigger custom events. This can be done with or without optional environment variables.

```lua
-- Trigger a custom event
sbar.trigger("my_custom_event")
```

```lua
-- Trigger with environment variables
sbar.trigger("my_custom_event", {
  INFO = "some_value",
  DATA = "additional_data"
})
```

--------------------------------

### Trigger SketchyBar Event

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Manually triggers a SketchyBar event, optionally with an environment table.

```lua
sbar.trigger(<event>, <optional: env_table>)
```

--------------------------------

### Multiple Bar Instances (sbar.set_bar_name)

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Target a different SketchyBar instance by name. Allows managing multiple independent status bars.

```APIDOC
## sbar.set_bar_name - Multiple Bar Instances

Target a different SketchyBar instance by name.

### Example: Set bar name and apply settings
```lua
sbar = require("sketchybar")
sbar.set_bar_name("bottom_bar")

-- All subsequent commands target "bottom_bar" instance
sbar.bar({ height = 30 })
```
```

--------------------------------

### Add a Space Item Associated with a macOS Space

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Adds a 'space' item that is linked to a specific macOS space (e.g., space 1). It configures the icon string, padding, and colors for normal and highlighted states.

```lua
-- Add a space item associated with a macOS space
local space = sbar.add("space", {
  associated_space = 1,
  icon = {
    string = "1",
    padding_left = 10,
    padding_right = 10,
    color = 0xffffffff,
    highlight_color = 0xffed8796,
  },
})
```

--------------------------------

### sbar.add - Adding Items API

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Add bar items (item, space, alias, bracket, slider, graph, event). Returns an item object for further operations.

```APIDOC
## sbar.add - Adding Items

Add bar items (item, space, alias, bracket, slider, graph, event). Returns an item object for further operations.

```lua
-- Add a simple item (name auto-generated)
local front_app = sbar.add("item", {
  icon = { drawing = false },
  label = {
    font = { style = "Black", size = 12.0 }
  }
})

-- Add a named item with position
local calendar = sbar.add("item", "my_calendar", {
  position = "right",
  icon = { padding_right = 0 },
  label = { width = 45, align = "right" },
  update_freq = 15,
})

-- Add a space item associated with a macOS space
local space = sbar.add("space", {
  associated_space = 1,
  icon = {
    string = "1",
    padding_left = 10,
    padding_right = 10,
    color = 0xffffffff,
    highlight_color = 0xffed8796,
  },
})

-- Add a bracket grouping multiple items
local spaces = {"space_1", "space_2", "space_3"}
sbar.add("bracket", spaces, {
  background = {
    color = 0xff363a4f,
    border_color = 0xff494d64
  }
})

-- Add a slider with width parameter
local volume_slider = sbar.add("slider", 100, {
  position = "right",
  slider = {
    highlight_color = 0xff8aadf4,
    width = 0,
    background = {
      height = 6,
      corner_radius = 3,
      color = 0xff494d64,
    },
    knob = { string = "􀀁", drawing = false },
  },
})

-- Add a custom event
local my_event = sbar.add("event", "my_custom_event")

-- Add event with NSDistributedNotificationCenter
local wake_event = sbar.add("event", "system_woke", "com.apple.screenIsUnlocked")
```
```

--------------------------------

### Update Item Icon and Label with Nested Tables

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Updates the icon and label properties of an item ('battery') using nested tables to specify the string and color for the icon, and the string and drawing state for the label.

```lua
-- Update multiple properties with nested tables
battery:set({
  icon = {
    string = "􀛨",
    color = 0xff8aadf4
  },
  label = {
    string = "85%",
    drawing = true
  }
})
```

--------------------------------

### Configure Bar Properties

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Sets properties for the SketchyBar. The property table uses sub-tables to represent nested properties, replacing dots used in the shell API.

```lua
sbar.bar(<property_table>)
```

--------------------------------

### Update Item Properties Using Item Name

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Updates the icon and label properties of an existing item ('my_calendar') by directly referencing its name.

```lua
-- Using item name directly
sbar.set("my_calendar", {
  icon = "Mon. 15 Jan.",
  label = "14:30"
})
```

--------------------------------

### Set Default Item Properties

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Defines default properties for all menu bar items, including font styles, colors, and padding for labels, icons, and backgrounds. Nested tables are used for sub-properties.

```lua
sbar.default({
  updates = "when_shown",
  icon = {
    font = {
      family = "SF Pro",
      style = "Bold",
      size = 14.0
    },
    color = 0xffffffff,
    padding_left = 4,
    padding_right = 4,
  },
  label = {
    font = {
      family = "SF Pro",
      style = "Semibold",
      size = 13.0
    },
    color = 0xffffffff,
    padding_left = 4,
    padding_right = 4,
  },
  background = {
    height = 26,
    corner_radius = 9,
    border_width = 2,
  },
  popup = {
    background = {
      border_width = 2,
      corner_radius = 9,
      border_color = 0xff494d64,
      color = 0xff1e1e2e,
      shadow = { drawing = true },
    },
    blur_radius = 20,
  },
  padding_left = 5,
  padding_right = 5
})
```

--------------------------------

### Animate SketchyBar Properties

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Animates SketchyBar properties over a specified duration and curve. The animation commands should be placed within the provided Lua function.

```lua
sbar.animate(<curve>, <duration>, <lua_function>)
```

--------------------------------

### Trigger Events (sbar.trigger)

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Manually trigger custom events, optionally with environment variables. Useful for custom event-driven logic.

```APIDOC
## sbar.trigger - Trigger Events

Manually trigger custom events with optional environment variables.

### Example: Trigger a custom event
```lua
sbar.trigger("my_custom_event")
```

### Example: Trigger with environment variables
```lua
sbar.trigger("my_custom_event", {
  INFO = "some_value",
  DATA = "additional_data"
})
```
```

--------------------------------

### Update Item Label Using Item Object

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Updates the label property of an existing item ('front_app') using its Lua object reference.

```lua
-- Using the item object
front_app:set({
  label = { string = "Safari" }
})
```

--------------------------------

### Push Graph Data (graph:push)

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Push float values (0-1) to a graph item. Used for visualizing time-series data like CPU usage.

```APIDOC
## graph:push - Push Graph Data

Push float values (0-1) to a graph item.

### Example: Push CPU usage values
```lua
local cpu_graph = sbar.add("graph", "cpu", 100, {
  position = "right",
  width = 100,
})

-- Push CPU usage values (normalized to 0-1)
cpu_graph:push({ 0.25, 0.30, 0.28, 0.45, 0.60 })
```
```

--------------------------------

### Set Item Properties

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Sets properties for an existing SketchyBar item. This method is called on an item object returned by `sbar.add`.

```lua
item:set(<property_table>)
```

--------------------------------

### Query Domain API

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Query the current properties of an element.

```APIDOC
## Query Element Properties

Retrieve the current properties of an element.

### Method
```lua
local info = item:query()
```

### Returns
- **info** (table) - A Lua table containing the element's properties. Nested properties are represented as sub-tables.

**Example:**
```lua
local left_padding = front_app:query().icon.padding_left
```
```

--------------------------------

### Add SketchyBar Elements

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Adds various elements to the SketchyBar, such as items, spaces, aliases, brackets, sliders, or events. Optional names can be provided for targeting.

```lua
local item = sbar.add(<"item", "space", "alias">, <optional: name>, <property_table>)
```

```lua
local bracket = sbar.add("bracket", <optional: name>, <member_table>, <property_table>)
```

```lua
local slider = sbar.add(<"slider", "graph">, <optional: name>, <width>, <property_table>)
```

```lua
local event = sbar.add("event", <name>, <optional: NSDistributedNotification>)
```

--------------------------------

### Push Domain API

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Push data to a graph element.

```APIDOC
## Push Data to Graph

Push values to a graph element.

### Method
```lua
graph:push(<float_table>)
```

### Parameters
- **float_table** (table) - A table of floating-point numbers, where each value should be between 0 and 1.
```

--------------------------------

### Set Domain API

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Update properties of an existing element using the `set` method on the element object.

```APIDOC
## Set Element Properties

Update properties of an existing element.

### Method
```lua
item:set(<property_table>)
```

### Parameters
- **property_table** (table) - A Lua table with key-value pairs to update.
```

--------------------------------

### Execute Shell Command Asynchronously

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Execute shell commands asynchronously without blocking the event loop. JSON output is automatically parsed into a Lua table.

```lua
-- Simple async execution (fire and forget)
sbar.exec("yabai -m space --focus 1")
```

```lua
-- With callback for result handling
sbar.exec("pmset -g batt", function(result, exit_code)
  local found, _, charge = result:find("(%d+)%%")
  if found then
    battery:set({ label = charge .. "%" })
  end
end)
```

```lua
-- Execute with JSON output (auto-parsed to Lua table)
sbar.exec("yabai -m query --spaces", function(spaces, exit_code)
  -- 'spaces' is already a Lua table
  for i, space in ipairs(spaces) do
    print("Space " .. i .. " has " .. #space.windows .. " windows")
  end
end)
```

```lua
-- Volume control via osascript
volume_slider:subscribe("mouse.clicked", function(env)
  sbar.exec("osascript -e 'set volume output volume " .. env["PERCENTAGE"] .. "'")
end)
```

--------------------------------

### Push Data to Graph

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Pushes float values (between 0 and 1) to a graph element. This is used for displaying dynamic data like performance metrics.

```lua
graph:push(<float_table>)
```

--------------------------------

### Query Item State

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Query the current state of an item, which returns a Lua table containing all its properties. This is useful for conditional logic based on the item's current status.

```lua
-- Get slider width
local slider_width = volume_slider:query().slider.width
```

```lua
-- Get icon padding
local padding = front_app:query().icon.padding_left
```

```lua
-- Conditional logic based on current state
if tonumber(volume_slider:query().slider.width) > 0 then
  -- Slider is visible
  animate_slider_width(0)
else
  -- Slider is hidden
  animate_slider_width(100)
end
```

--------------------------------

### Toggle Volume Slider Visibility

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Toggle the visibility of the volume slider by animating its width to 0 or 100. This is triggered by a mouse click on the volume icon.

```lua
-- Toggle volume slider visibility on click
volume_icon:subscribe("mouse.clicked", function()
  if tonumber(volume_slider:query().slider.width) > 0 then
    animate_slider_width(0)
  else
    animate_slider_width(100)
  end
end)
```

--------------------------------

### Execute Shell Commands Asynchronously

Source: https://github.com/felixkratz/sbarlua/blob/main/README.md

Executes a shell command asynchronously without blocking the Lua event handler. Optionally provides a callback function to handle the command's result.

```lua
sbar.exec(<command>, [Optional: <lua_function>])
```

```lua
sbar.exec("sleep 5 && echo TEST", function(result, exit_code)
  print(result)
end)
```

--------------------------------

### Push Graph Data

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Push float values (normalized between 0 and 1) to a graph item. This is typically used for visualizing real-time data like CPU usage.

```lua
local cpu_graph = sbar.add("graph", "cpu", 100, {
  position = "right",
  width = 100,
})
```

```lua
-- Push CPU usage values (normalized to 0-1)
cpu_graph:push({ 0.25, 0.30, 0.28, 0.45, 0.60 })
```

--------------------------------

### Animate Multiple Properties

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Animate multiple properties of an item simultaneously using a specified curve and duration. This allows for complex visual effects.

```lua
-- Animate multiple properties
sbar.animate("sin", 20, function()
  my_item:set({
    icon = { color = 0xffed8796 },
    background = { color = 0xff363a4f }
  })
end)
```

--------------------------------

### Add Event with NSDistributedNotificationCenter

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Adds an event that listens to a system notification from NSDistributedNotificationCenter, such as 'com.apple.screenIsUnlocked'.

```lua
-- Add event with NSDistributedNotificationCenter
local wake_event = sbar.add("event", "system_woke", "com.apple.screenIsUnlocked")
```

--------------------------------

### item:set - Update Item Properties API

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Update properties on an existing item using the item object or name.

```APIDOC
## item:set - Update Item Properties

Update properties on an existing item using the item object or name.

```lua
-- Using the item object
front_app:set({
  label = { string = "Safari" }
})

-- Using item name directly
sbar.set("my_calendar", {
  icon = "Mon. 15 Jan.",
  label = "14:30"
})

-- Update multiple properties with nested tables
battery:set({
  icon = {
    string = "􀛨",
    color = 0xff8aadf4
  },
  label = {
    string = "85%",
    drawing = true
  }
})
```
```

--------------------------------

### sbar.default - Default Item Properties API

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Set default properties that apply to all items unless overridden. Uses nested tables for sub-properties.

```APIDOC
## sbar.default - Default Item Properties

Set default properties that apply to all items unless overridden. Uses nested tables for sub-properties.

```lua
sbar.default({
  updates = "when_shown",
  icon = {
    font = {
      family = "SF Pro",
      style = "Bold",
      size = 14.0
    },
    color = 0xffffffff,
    padding_left = 4,
    padding_right = 4,
  },
  label = {
    font = {
      family = "SF Pro",
      style = "Semibold",
      size = 13.0
    },
    color = 0xffffffff,
    padding_left = 4,
    padding_right = 4,
  },
  background = {
    height = 26,
    corner_radius = 9,
    border_width = 2,
  },
  popup = {
    background = {
      border_width = 2,
      corner_radius = 9,
      border_color = 0xff494d64,
      color = 0xff1e1e2e,
      shadow = { drawing = true },
    },
    blur_radius = 20,
  },
  padding_left = 5,
  padding_right = 5
})
```
```

--------------------------------

### Animate Slider Width

Source: https://context7.com/felixkratz/sbarlua/llms.txt

Animate the width of a slider using a specified curve and duration. This function is designed for smooth visual transitions.

```lua
-- Animate slider width with tanh curve over 30 animation steps
local function animate_slider_width(width)
  sbar.animate("tanh", 30.0, function()
    volume_slider:set({ slider = { width = width }})
  end)
end
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.