chore: first version

2026-07-30 18:39:38 +02:00
commit c953ca8460
54 changed files with 4197 additions and 0 deletions
@@ -0,0 +1,149 @@
+---
+name: add-dock-band
+description: >-
+  Add dock band support to your Command Palette extension for persistent toolbar widgets.
+  Use when asked to add dock support, toolbar buttons, persistent UI widgets,
+  taskbar integration, live-updating status displays, quick-access buttons,
+  or always-visible controls. Supports single buttons, multi-button strips,
+  and live-updating content.
+---
+
+# Add Dock Band Support
+
+The Command Palette Dock is a persistent toolbar at the edge of the user's screen. Your extension can provide **dock bands** — strips of items that appear in the Dock — giving users quick access to commands without opening the full Command Palette.
+
+## When to Use This Skill
+
+- Adding a quick-access button to the persistent toolbar
+- Creating a multi-button toolbar strip
+- Displaying live-updating information (clock, CPU usage, etc.)
+- Providing frequently-used commands without opening the full palette
+
+## Prerequisites
+
+- Command Palette Extension SDK version 0.9 or later (`Microsoft.CommandPalette.Extensions` ≥ 0.9.260303001)
+
+## Quick Start: Single Button Dock Band
+
+Override `GetDockBands()` in your `CommandProvider`:
+
+```csharp
+public partial class MyCommandsProvider : CommandProvider
+{
+    private readonly ICommandItem[] _commands;
+    private readonly ICommandItem _dockBand;
+
+    public MyCommandsProvider()
+    {
+        DisplayName = "My Extension";
+        Id = "com.mycompany.myextension"; // Unique ID required for dock
+
+        var mainPage = new MyPage();
+        _dockBand = new CommandItem(mainPage) { Title = DisplayName };
+        _commands = [new CommandItem(mainPage) { Title = DisplayName }];
+    }
+
+    public override ICommandItem[] TopLevelCommands() => _commands;
+
+    public override ICommandItem[]? GetDockBands() => [_dockBand];
+}
+```
+
+## Multi-Button Dock Band
+
+Use `WrappedDockItem` to create a band with multiple buttons:
+
+```csharp
+public override ICommandItem[]? GetDockBands()
+{
+    var button1 = new ListItem(new OpenUrlCommand("https://github.com"))
+    {
+        Title = "GitHub",
+        Icon = new IconInfo("\uE774"),
+    };
+    var button2 = new ListItem(new OpenUrlCommand("https://learn.microsoft.com"))
+    {
+        Title = "Learn",
+        Icon = new IconInfo("\uE82D"),
+    };
+
+    var band = new WrappedDockItem(
+        [button1, button2],
+        "com.mycompany.myextension.quicklinks", // Unique band ID
+        "Quick Links");
+
+    return [band];
+}
+```
+
+## Live-Updating Dock Band
+
+Create a dock band that updates its content periodically (like a clock):
+
+```csharp
+internal sealed partial class LiveStatusBand : ListItem
+{
+    private readonly System.Timers.Timer _timer;
+
+    public LiveStatusBand()
+        : base(new NoOpCommand() { Result = CommandResult.KeepOpen() })
+    {
+        Title = DateTime.Now.ToString("HH:mm");
+        Icon = new IconInfo("\uE823"); // Clock icon
+
+        _timer = new System.Timers.Timer(60_000); // Update every minute
+        _timer.Elapsed += (s, e) =>
+        {
+            Title = DateTime.Now.ToString("HH:mm");
+            Subtitle = DateTime.Now.ToString("dddd, MMMM d");
+        };
+        _timer.Start();
+    }
+}
+
+// In CommandProvider:
+public override ICommandItem[]? GetDockBands()
+{
+    var band = new WrappedDockItem(
+        [new LiveStatusBand()],
+        "com.mycompany.myextension.status",
+        "Live Status");
+    return [band];
+}
+```
+
+## How Dock Bands Render
+
+| Command Type on ICommandItem | Dock Behavior |
+|------------------------------|---------------|
+| `IInvokableCommand` | Single button that executes the command |
+| `IListPage` | Each list item renders as a separate button in one band |
+| `IContentPage` | Single expandable button with a flyout |
+
+## Support Pinning Nested Commands
+
+By default, only top-level commands and dock bands can be pinned. To allow pinning nested commands:
+
+```csharp
+public override ICommandItem? GetCommandItem(string id)
+{
+    // Look up commands by their Id
+    foreach (var item in GetAllCommands())
+    {
+        if (item?.Command is ICommand cmd && cmd.Id == id)
+            return item;
+    }
+    return null;
+}
+```
+
+## Important Notes
+
+- All dock band `ICommandItem` objects must have a `Command` with a **non-empty `Id`** — items without an ID are ignored
+- Set `Id` on your `CommandProvider` (e.g., `Id = "com.mycompany.myextension"`)
+- Use `WrappedDockItem` for multi-button bands backed by a `ListPage`
+- Keep dock band updates lightweight — they run frequently
+
+## Documentation
+
+- [Adding Dock support](https://learn.microsoft.com/windows/powertoys/command-palette/adding-dock-support)