wsh setbg + updated tab background docs

cmd/wsh/cmd/csscolormap.go

@@ -0,0 +1,147 @@
+// Copyright 2024, Command Line Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+var CssColorNames = map[string]bool{
+	"aliceblue":            true,
+	"antiquewhite":         true,
+	"aqua":                 true,
+	"aquamarine":           true,
+	"azure":                true,
+	"beige":                true,
+	"bisque":               true,
+	"black":                true,
+	"blanchedalmond":       true,
+	"blue":                 true,
+	"blueviolet":           true,
+	"brown":                true,
+	"burlywood":            true,
+	"cadetblue":            true,
+	"chartreuse":           true,
+	"chocolate":            true,
+	"coral":                true,
+	"cornflowerblue":       true,
+	"cornsilk":             true,
+	"crimson":              true,
+	"cyan":                 true,
+	"darkblue":             true,
+	"darkcyan":             true,
+	"darkgoldenrod":        true,
+	"darkgray":             true,
+	"darkgreen":            true,
+	"darkkhaki":            true,
+	"darkmagenta":          true,
+	"darkolivegreen":       true,
+	"darkorange":           true,
+	"darkorchid":           true,
+	"darkred":              true,
+	"darksalmon":           true,
+	"darkseagreen":         true,
+	"darkslateblue":        true,
+	"darkslategray":        true,
+	"darkturquoise":        true,
+	"darkviolet":           true,
+	"deeppink":             true,
+	"deepskyblue":          true,
+	"dimgray":              true,
+	"dodgerblue":           true,
+	"firebrick":            true,
+	"floralwhite":          true,
+	"forestgreen":          true,
+	"fuchsia":              true,
+	"gainsboro":            true,
+	"ghostwhite":           true,
+	"gold":                 true,
+	"goldenrod":            true,
+	"gray":                 true,
+	"green":                true,
+	"greenyellow":          true,
+	"honeydew":             true,
+	"hotpink":              true,
+	"indianred":            true,
+	"indigo":               true,
+	"ivory":                true,
+	"khaki":                true,
+	"lavender":             true,
+	"lavenderblush":        true,
+	"lawngreen":            true,
+	"lemonchiffon":         true,
+	"lightblue":            true,
+	"lightcoral":           true,
+	"lightcyan":            true,
+	"lightgoldenrodyellow": true,
+	"lightgray":            true,
+	"lightgreen":           true,
+	"lightpink":            true,
+	"lightsalmon":          true,
+	"lightseagreen":        true,
+	"lightskyblue":         true,
+	"lightslategray":       true,
+	"lightsteelblue":       true,
+	"lightyellow":          true,
+	"lime":                 true,
+	"limegreen":            true,
+	"linen":                true,
+	"magenta":              true,
+	"maroon":               true,
+	"mediumaquamarine":     true,
+	"mediumblue":           true,
+	"mediumorchid":         true,
+	"mediumpurple":         true,
+	"mediumseagreen":       true,
+	"mediumslateblue":      true,
+	"mediumspringgreen":    true,
+	"mediumturquoise":      true,
+	"mediumvioletred":      true,
+	"midnightblue":         true,
+	"mintcream":            true,
+	"mistyrose":            true,
+	"moccasin":             true,
+	"navajowhite":          true,
+	"navy":                 true,
+	"oldlace":              true,
+	"olive":                true,
+	"olivedrab":            true,
+	"orange":               true,
+	"orangered":            true,
+	"orchid":               true,
+	"palegoldenrod":        true,
+	"palegreen":            true,
+	"paleturquoise":        true,
+	"palevioletred":        true,
+	"papayawhip":           true,
+	"peachpuff":            true,
+	"peru":                 true,
+	"pink":                 true,
+	"plum":                 true,
+	"powderblue":           true,
+	"purple":               true,
+	"red":                  true,
+	"rosybrown":            true,
+	"royalblue":            true,
+	"saddlebrown":          true,
+	"salmon":               true,
+	"sandybrown":           true,
+	"seagreen":             true,
+	"seashell":             true,
+	"sienna":               true,
+	"silver":               true,
+	"skyblue":              true,
+	"slateblue":            true,
+	"slategray":            true,
+	"snow":                 true,
+	"springgreen":          true,
+	"steelblue":            true,
+	"tan":                  true,
+	"teal":                 true,
+	"thistle":              true,
+	"tomato":               true,
+	"turquoise":            true,
+	"violet":               true,
+	"wheat":                true,
+	"white":                true,
+	"whitesmoke":           true,
+	"yellow":               true,
+	"yellowgreen":          true,
+}

cmd/wsh/cmd/wshcmd-setbg.go

@@ -0,0 +1,186 @@
+// Copyright 2024, Command Line Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package cmd
+
+import (
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/wavetermdev/waveterm/pkg/util/utilfn"
+	"github.com/wavetermdev/waveterm/pkg/wavebase"
+	"github.com/wavetermdev/waveterm/pkg/wshrpc"
+	"github.com/wavetermdev/waveterm/pkg/wshrpc/wshclient"
+)
+
+var setBgCmd = &cobra.Command{
+	Use:   "setbg [--opacity value] [--tile|--center] [--scale value] (image-path|\"#color\"|color-name)",
+	Short: "set background image or color for a tab",
+	Long: `Set a background image or color for a tab. Colors can be specified as:
+  - A quoted hex value like "#ff0000" (quotes required to prevent # being interpreted as a shell comment)
+  - A CSS color name like "blue" or "forestgreen"
+Or provide a path to a supported image file (jpg, png, gif, webp, or svg).
+
+You can also:
+  - Use --clear to remove the background
+  - Use --opacity without other arguments to change just the opacity
+  - Use --center for centered images without scaling (good for logos)
+  - Use --scale with --center to control image size
+  - Use --print to see the metadata without applying it`,
+	RunE:    setBgRun,
+	PreRunE: preRunSetupRpcClient,
+}
+
+var (
+	setBgOpacity float64
+	setBgTile    bool
+	setBgCenter  bool
+	setBgSize    string
+	setBgClear   bool
+	setBgPrint   bool
+)
+
+func init() {
+	rootCmd.AddCommand(setBgCmd)
+	setBgCmd.Flags().Float64Var(&setBgOpacity, "opacity", 0.5, "background opacity (0.0-1.0)")
+	setBgCmd.Flags().BoolVar(&setBgTile, "tile", false, "tile the background image")
+	setBgCmd.Flags().BoolVar(&setBgCenter, "center", false, "center the image without scaling")
+	setBgCmd.Flags().StringVar(&setBgSize, "size", "auto", "size for centered images (px, %, or auto)")
+	setBgCmd.Flags().BoolVar(&setBgClear, "clear", false, "clear the background")
+	setBgCmd.Flags().BoolVar(&setBgPrint, "print", false, "print the metadata without applying it")
+
+	// Make tile and center mutually exclusive
+	setBgCmd.MarkFlagsMutuallyExclusive("tile", "center")
+}
+
+func validateHexColor(color string) error {
+	if !strings.HasPrefix(color, "#") {
+		return fmt.Errorf("color must start with #")
+	}
+	colorHex := color[1:]
+	if len(colorHex) != 6 && len(colorHex) != 8 {
+		return fmt.Errorf("color must be in #RRGGBB or #RRGGBBAA format")
+	}
+	_, err := hex.DecodeString(colorHex)
+	if err != nil {
+		return fmt.Errorf("invalid hex color: %v", err)
+	}
+	return nil
+}
+
+func setBgRun(cmd *cobra.Command, args []string) (rtnErr error) {
+	defer func() {
+		sendActivity("setbg", rtnErr == nil)
+	}()
+
+	// Create base metadata
+	meta := map[string]interface{}{}
+
+	// Handle opacity-only change or clear
+	if len(args) == 0 {
+		if !cmd.Flags().Changed("opacity") && !setBgClear {
+			OutputHelpMessage(cmd)
+			return fmt.Errorf("setbg requires an image path or color value")
+		}
+		if setBgOpacity < 0 || setBgOpacity > 1 {
+			return fmt.Errorf("opacity must be between 0.0 and 1.0")
+		}
+		if cmd.Flags().Changed("opacity") {
+			meta["bg:opacity"] = setBgOpacity
+		}
+	} else if len(args) > 1 {
+		OutputHelpMessage(cmd)
+		return fmt.Errorf("too many arguments")
+	} else {
+		// Handle background setting
+		meta["bg:*"] = true
+		if setBgOpacity < 0 || setBgOpacity > 1 {
+			return fmt.Errorf("opacity must be between 0.0 and 1.0")
+		}
+		meta["bg:opacity"] = setBgOpacity
+
+		input := args[0]
+		var bgStyle string
+
+		// Check for hex color
+		if strings.HasPrefix(input, "#") {
+			if err := validateHexColor(input); err != nil {
+				return err
+			}
+			bgStyle = input
+		} else if CssColorNames[strings.ToLower(input)] {
+			// Handle CSS color name
+			bgStyle = strings.ToLower(input)
+		} else {
+			// Handle image input
+			absPath, err := filepath.Abs(wavebase.ExpandHomeDirSafe(input))
+			if err != nil {
+				return fmt.Errorf("resolving image path: %v", err)
+			}
+
+			fileInfo, err := os.Stat(absPath)
+			if err != nil {
+				return fmt.Errorf("cannot access image file: %v", err)
+			}
+			if fileInfo.IsDir() {
+				return fmt.Errorf("path is a directory, not an image file")
+			}
+
+			mimeType := utilfn.DetectMimeType(absPath, fileInfo, true)
+			switch mimeType {
+			case "image/jpeg", "image/png", "image/gif", "image/webp", "image/svg+xml":
+				// Valid image type
+			default:
+				return fmt.Errorf("file does not appear to be a valid image (detected type: %s)", mimeType)
+			}
+
+			// Create URL-safe path
+			escapedPath := strings.ReplaceAll(absPath, "'", "\\'")
+			bgStyle = fmt.Sprintf("url('%s')", escapedPath)
+
+			switch {
+			case setBgTile:
+				bgStyle += " repeat"
+			case setBgCenter:
+				bgStyle += fmt.Sprintf(" no-repeat center/%s", setBgSize)
+			default:
+				bgStyle += " center/cover no-repeat"
+			}
+		}
+
+		meta["bg"] = bgStyle
+	}
+
+	if setBgPrint {
+		jsonBytes, err := json.MarshalIndent(meta, "", "  ")
+		if err != nil {
+			return fmt.Errorf("error formatting metadata: %v", err)
+		}
+		WriteStdout(string(jsonBytes) + "\n")
+		return nil
+	}
+
+	// Resolve tab reference
+	oRef, err := resolveSimpleId("tab")
+	if err != nil {
+		return err
+	}
+
+	// Send RPC request
+	setMetaWshCmd := wshrpc.CommandSetMetaData{
+		ORef: *oRef,
+		Meta: meta,
+	}
+	err = wshclient.SetMetaCommand(RpcClient, setMetaWshCmd, &wshrpc.RpcOpts{Timeout: 2000})
+	if err != nil {
+		return fmt.Errorf("setting background: %v", err)
+	}
+
+	WriteStdout("background set\n")
+	return nil
+}

docs/docs/customization.mdx

@@ -65,6 +65,41 @@ You can also suppress the help widgets in the bottom right by setting the config
 
 <div style={{ clear: "both" }} />
 
+## Tab Backgrounds
+
+Wave supports powerful custom backgrounds for your tabs using images, patterns, gradients, and colors. The quickest way to set an image background is using the `wsh setbg` command:
+
+```bash
+# Set an image background with 50% opacity (default)
+wsh setbg ~/pictures/background.jpg
+
+# Set a color background (use quotes to prevent # being interpreted as a shell comment)
+wsh setbg "#ff0000"          # hex color
+wsh setbg forestgreen        # CSS color name
+
+# Adjust opacity
+wsh setbg --opacity 0.3 ~/pictures/light-pattern.png
+wsh setbg --opacity 0.7      # change only opacity of current background
+
+# Image positioning options
+wsh setbg --tile ~/pictures/texture.png          # create tiled pattern
+wsh setbg --center ~/pictures/logo.png           # center without scaling
+wsh setbg --center --size 200px ~/pictures/logo.png  # center with specific size (px, %, auto)
+
+# Remove background
+wsh setbg --clear
+```
+
+You can use any JPEG, PNG, GIF, WebP, or SVG image as your background. The `--center` option is particularly useful for logos or icons where you want to maintain the original size.
+
+To preview the metadata for any background without applying it, use the `--print` flag:
+
+```bash
+wsh setbg --print "#ff0000"
+```
+
+For more advanced customization options including gradients, colors, and saving your own background presets, check out our [Background Configuration](/presets#background-configurations) documentation.
+
 ## Presets
 
 For more advanced customization, to set up multiple AI models, and your own tab backgrounds, check out our [Presets Documentation](./presets).