From 73ca25500b282ae32ba50c0243750a28cab3cb00 Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Fri, 26 Dec 2025 21:08:40 -0800 Subject: [PATCH] docs(config): ensure all public-facing static config opts have docstrings --- komorebi/src/animation/mod.rs | 25 ++ komorebi/src/core/animation.rs | 33 ++ komorebi/src/core/arrangement.rs | 4 + komorebi/src/core/config_generation.rs | 23 ++ komorebi/src/core/default_layout.rs | 92 +++++- komorebi/src/core/layout.rs | 2 + komorebi/src/core/mod.rs | 15 +- komorebi/src/core/rect.rs | 5 + komorebi/src/static_config.rs | 12 + komorebi/src/window.rs | 2 + nix/komorebi-bar-options.nix | 70 +++-- nix/komorebi-options.nix | 77 ++--- schema.asc.json | 99 ++++-- schema.bar.json | 64 +++- schema.json | 406 ++++++++++++++++++++----- 15 files changed, 759 insertions(+), 170 deletions(-) diff --git a/komorebi/src/animation/mod.rs b/komorebi/src/animation/mod.rs index 651a06a7..a368ad6b 100644 --- a/komorebi/src/animation/mod.rs +++ b/komorebi/src/animation/mod.rs @@ -24,8 +24,33 @@ use serde::Serialize; #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] #[serde(untagged)] +/// Animation configuration +/// +/// This can be either global: +/// ```json +/// { +/// "enabled": true, +/// "style": "EaseInSine", +/// "fps": 60, +/// "duration": 250 +/// } +/// ``` +/// +/// Or scoped by an animation kind prefix: +/// ```json +/// { +/// "movement": { +/// "enabled": true, +/// "style": "EaseInSine", +/// "fps": 60, +/// "duration": 250 +/// } +/// } +/// ``` pub enum PerAnimationPrefixConfig { + /// Animation configuration prefixed for a specific animation kind Prefix(HashMap), + /// Animation configuration for all animation kinds Global(T), } diff --git a/komorebi/src/core/animation.rs b/komorebi/src/core/animation.rs index 5201976d..87492cc4 100644 --- a/komorebi/src/core/animation.rs +++ b/komorebi/src/core/animation.rs @@ -8,39 +8,72 @@ use strum::EnumString; #[derive(Copy, Clone, Debug, Display, EnumString, ValueEnum, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Mathematical function which describes the rate at which a value changes pub enum AnimationStyle { + /// Linear Linear, + /// Ease in sine EaseInSine, + /// Ease out sine EaseOutSine, + /// Ease in out sine EaseInOutSine, + /// Ease in quad EaseInQuad, + /// Ease out quad EaseOutQuad, + /// Ease in out quad EaseInOutQuad, + /// Ease in cubic EaseInCubic, + /// Ease out cubic EaseOutCubic, + /// Ease in out cubic EaseInOutCubic, + /// Ease in quart EaseInQuart, + /// Ease out quart EaseOutQuart, + /// Ease in out quart EaseInOutQuart, + /// Ease in quint EaseInQuint, + /// Ease out quint EaseOutQuint, + /// Ease in out quint EaseInOutQuint, + /// Ease in expo EaseInExpo, + /// Ease out expo EaseOutExpo, + /// Ease in out expo EaseInOutExpo, + /// Ease in circ EaseInCirc, + /// Ease out circ EaseOutCirc, + /// Ease in out circ EaseInOutCirc, + /// Ease in back EaseInBack, + /// Ease out back EaseOutBack, + /// Ease in out back EaseInOutBack, + /// Ease in elastic EaseInElastic, + /// Ease out elastic EaseOutElastic, + /// Ease in out elastic EaseInOutElastic, + /// Ease in bounce EaseInBounce, + /// Ease out bounce EaseOutBounce, + /// Ease in out bounce EaseInOutBounce, #[value(skip)] + /// Custom Cubic Bézier function CubicBezier(f64, f64, f64, f64), } diff --git a/komorebi/src/core/arrangement.rs b/komorebi/src/core/arrangement.rs index 9396035b..1c1d5850 100644 --- a/komorebi/src/core/arrangement.rs +++ b/komorebi/src/core/arrangement.rs @@ -601,9 +601,13 @@ impl Arrangement for DefaultLayout { #[derive(Clone, Copy, Debug, Serialize, Deserialize, Display, EnumString, ValueEnum, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// An axis on which to perform an operation pub enum Axis { + /// Horizontal axis Horizontal, + /// Vertical axis Vertical, + /// Both horizontal and vertical axes HorizontalAndVertical, } diff --git a/komorebi/src/core/config_generation.rs b/komorebi/src/core/config_generation.rs index ceb3aa70..021aaa5f 100644 --- a/komorebi/src/core/config_generation.rs +++ b/komorebi/src/core/config_generation.rs @@ -21,41 +21,64 @@ pub enum ApplicationOptions { #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] #[serde(untagged)] +/// Rule for matching applications pub enum MatchingRule { + /// Simple matching rule which must evaluate to true Simple(IdWithIdentifier), + /// Composite matching rule where all conditions must evaluate to true Composite(Vec), } #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Rule for assigning applications to a workspace pub struct WorkspaceMatchingRule { + /// Target monitor index pub monitor_index: usize, + /// Target workspace index pub workspace_index: usize, + /// Matching rule for the application pub matching_rule: MatchingRule, + /// Whether to apply the rule only when the application is initially launched pub initial_only: bool, } #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Rule for matching applications pub struct IdWithIdentifier { + /// Kind of identifier to target pub kind: ApplicationIdentifier, + /// Target identifier pub id: String, #[serde(skip_serializing_if = "Option::is_none")] + /// Matching strategy to use pub matching_strategy: Option, } #[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize, Display)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Strategy for matching identifiers pub enum MatchingStrategy { + /// Should not be used, only kept for backward compatibility Legacy, + /// Equals Equals, + /// Starts With StartsWith, + /// Ends With EndsWith, + /// Contains Contains, + /// Regex Regex, + /// Does not end with DoesNotEndWith, + /// Does not start with DoesNotStartWith, + /// Does not equal DoesNotEqual, + /// Does not contain DoesNotContain, } diff --git a/komorebi/src/core/default_layout.rs b/komorebi/src/core/default_layout.rs index 264bb7e1..3e789381 100644 --- a/komorebi/src/core/default_layout.rs +++ b/komorebi/src/core/default_layout.rs @@ -10,22 +10,110 @@ use strum::EnumString; #[derive( Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq, Display, EnumString, ValueEnum, )] -#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema), schemars(extend("default" = Self::BSP)))] +/// A predefined komorebi layout pub enum DefaultLayout { + /// BSP Layout + /// + /// ``` + /// +-------+-----+ + /// | | | + /// | +--+--+ + /// | | |--| + /// +-------+--+--+ + /// ``` BSP, + /// Columns Layout + /// + /// ``` + /// +--+--+--+--+ + /// | | | | | + /// | | | | | + /// | | | | | + /// +--+--+--+--+ + /// ``` Columns, + /// Rows Layout + /// + /// ``` + /// +-----------+ + /// |-----------| + /// |-----------| + /// |-----------| + /// +-----------+ + /// ``` Rows, + /// Vertical Stack Layout + /// + /// ``` + /// +-------+-----+ + /// | | | + /// | +-----+ + /// | | | + /// +-------+-----+ + /// ``` VerticalStack, + /// Horizontal Stack Layout + /// + /// ``` + /// +------+------+ + /// | | + /// |------+------+ + /// | | | + /// +------+------+ + /// ``` HorizontalStack, + /// Ultrawide Vertical Stack Layout + /// + /// ``` + /// +-----+-----------+-----+ + /// | | | | + /// | | +-----+ + /// | | | | + /// | | +-----+ + /// | | | | + /// +-----+-----------+-----+ + /// ``` UltrawideVerticalStack, + /// Grid Layout + /// + /// ``` + /// +-----+-----+ +---+---+---+ +---+---+---+ +---+---+---+ + ///| | | | | | | | | | | | | | | + ///| | | | | | | | | | | | | +---+ + ///+-----+-----+ | +---+---+ +---+---+---+ +---+---| | + ///| | | | | | | | | | | | | +---+ + ///| | | | | | | | | | | | | | | + ///+-----+-----+ +---+---+---+ +---+---+---+ +---+---+---+ + /// 4 windows 5 windows 6 windows 7 windows + ///``` Grid, + /// Right Main Vertical Stack Layout + /// + /// ``` + /// +-----+-------+ + /// | | | + /// +-----+ | + /// | | | + /// +-----+-------+ + /// ``` RightMainVerticalStack, + /// Scrolling Layout + /// + /// ``` + /// +--+--+--+--+--+--+ + /// | | | | + /// | | | | + /// | | | | + /// +--+--+--+--+--+--+ + /// ``` Scrolling, // NOTE: If any new layout is added, please make sure to register the same in `DefaultLayout::cycle` } #[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Options for specific layouts pub struct LayoutOptions { /// Options related to the Scrolling layout pub scrolling: Option, @@ -35,6 +123,7 @@ pub struct LayoutOptions { #[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Options for the Scrolling layout pub struct ScrollingLayoutOptions { /// Desired number of visible columns (default: 3) pub columns: usize, @@ -44,6 +133,7 @@ pub struct ScrollingLayoutOptions { #[derive(Clone, Copy, Debug, Serialize, Deserialize, Eq, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Options for the Grid layout pub struct GridLayoutOptions { /// Maximum number of rows per grid column pub rows: usize, diff --git a/komorebi/src/core/layout.rs b/komorebi/src/core/layout.rs index a3ec0713..adf67773 100644 --- a/komorebi/src/core/layout.rs +++ b/komorebi/src/core/layout.rs @@ -6,7 +6,9 @@ use serde::Serialize; #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// A komorebi layout pub enum Layout { + /// A predefined komorebi layout Default(DefaultLayout), } diff --git a/komorebi/src/core/mod.rs b/komorebi/src/core/mod.rs index 5e7c362b..2df3874c 100644 --- a/komorebi/src/core/mod.rs +++ b/komorebi/src/core/mod.rs @@ -33,11 +33,12 @@ pub mod rect; Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize, Display, EnumString, ValueEnum, )] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Operation behaviour for temporarily unmanaged and floating windows pub enum OperationBehaviour { - /// Process komorebic commands on temporarily unmanaged/floated windows + /// Process commands on temporarily unmanaged/floated windows #[default] Op, - /// Ignore komorebic commands on temporarily unmanaged/floated windows + /// Ignore commands on temporarily unmanaged/floated windows NoOp, } @@ -93,6 +94,7 @@ pub struct WindowManagementBehaviour { Clone, Copy, Debug, Default, Serialize, Deserialize, Display, EnumString, ValueEnum, PartialEq, )] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Window container behaviour when a new window is opened pub enum WindowContainerBehaviour { /// Create a new container for each new window #[default] @@ -105,6 +107,7 @@ pub enum WindowContainerBehaviour { Clone, Copy, Debug, Default, Serialize, Deserialize, Display, EnumString, ValueEnum, PartialEq, )] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Floating layer behaviour when a new window is opened pub enum FloatingLayerBehaviour { /// Tile new windows (unless they match a float rule or float override is active) #[default] @@ -129,6 +132,7 @@ pub enum WindowHidingPosition { Clone, Copy, Debug, Default, Serialize, Deserialize, Display, EnumString, ValueEnum, PartialEq, )] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Placement behaviour for floating windows pub enum Placement { /// Does not change the size or position of the window #[default] @@ -168,6 +172,7 @@ impl Placement { Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize, Display, EnumString, ValueEnum, )] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Move behaviour when the operation works across a monitor boundary pub enum MoveBehaviour { /// Swap the window container with the window container at the edge of the adjacent monitor #[default] @@ -182,6 +187,7 @@ pub enum MoveBehaviour { Clone, Copy, Debug, Default, Serialize, Deserialize, Display, EnumString, ValueEnum, PartialEq, )] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Behaviour when an action would cross a monitor boundary pub enum CrossBoundaryBehaviour { /// Attempt to perform actions across a workspace boundary Workspace, @@ -194,13 +200,18 @@ pub enum CrossBoundaryBehaviour { Copy, Clone, Debug, Eq, PartialEq, Serialize, Deserialize, Display, EnumString, ValueEnum, )] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Application identifier pub enum ApplicationIdentifier { + /// Executable name #[serde(alias = "exe")] Exe, + /// Role or subrole #[serde(alias = "class")] Class, + /// Window title #[serde(alias = "title")] Title, + /// Executable path #[serde(alias = "path")] Path, } diff --git a/komorebi/src/core/rect.rs b/komorebi/src/core/rect.rs index 2c63395a..62525601 100644 --- a/komorebi/src/core/rect.rs +++ b/komorebi/src/core/rect.rs @@ -9,10 +9,15 @@ use serde::Serialize; #[derive(Debug, Default, Copy, Clone, Serialize, Deserialize, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Rectangle dimensions pub struct Rect { + /// Left point of the rectangle pub left: i32, + /// Top point of the rectangle pub top: i32, + /// Width of the recentangle (from the left point) pub right: i32, + /// Height of the rectangle (from the top point) pub bottom: i32, } diff --git a/komorebi/src/static_config.rs b/komorebi/src/static_config.rs index cb05e2f5..0bd1d6f5 100644 --- a/komorebi/src/static_config.rs +++ b/komorebi/src/static_config.rs @@ -94,6 +94,9 @@ mod defaults { #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Border colours for different container states +/// +/// These options will have no effect if a `theme` is set pub struct BorderColours { /// Border colour when the container contains a single window #[serde(skip_serializing_if = "Option::is_none")] @@ -117,6 +120,7 @@ pub struct BorderColours { #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Theme options pub struct ThemeOptions { /// Specify Light or Dark variant for theme generation #[serde(skip_serializing_if = "Option::is_none")] @@ -164,6 +168,7 @@ pub struct ThemeOptions { #[serde_with::serde_as] #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Wallpaper configuration pub struct Wallpaper { /// Path to the wallpaper image file #[serde_as(as = "ResolvedPathBuf")] @@ -181,6 +186,7 @@ pub struct Wallpaper { #[serde_with::serde_as] #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Workspace configuration pub struct WorkspaceConfig { /// Name pub name: String, @@ -328,6 +334,7 @@ impl From<&Workspace> for WorkspaceConfig { #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Monitor configuration pub struct MonitorConfig { /// Workspace configurations pub workspaces: Vec, @@ -403,6 +410,7 @@ impl From<&Monitor> for MonitorConfig { #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] #[serde(untagged)] +/// Path(s) to application-specific configuration file(s) pub enum AppSpecificConfigurationPath { /// A single applications.json file Single(#[serde_as(as = "ResolvedPathBuf")] PathBuf), @@ -568,6 +576,8 @@ pub struct StaticConfig { #[serde(skip_serializing_if = "Option::is_none")] pub animation: Option, /// Theme configuration options + /// + /// If a theme is specified, `border_colours` will have no effect #[serde(skip_serializing_if = "Option::is_none")] pub theme: Option, /// Identify applications which are slow to send initial event notifications @@ -594,6 +604,7 @@ pub struct StaticConfig { #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Animation configuration pub struct AnimationsConfig { /// Enable or disable animations #[cfg_attr(feature = "schemars", schemars(extend("default" = PerAnimationPrefixConfig::Global(false))))] @@ -615,6 +626,7 @@ pub struct AnimationsConfig { #[derive(Clone, Debug, Serialize, Deserialize, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] #[serde(tag = "palette")] +/// Komorebi theme pub enum KomorebiTheme { /// A theme from catppuccin-egui Catppuccin { diff --git a/komorebi/src/window.rs b/komorebi/src/window.rs index 4bb39a5b..8d096b09 100644 --- a/komorebi/src/window.rs +++ b/komorebi/src/window.rs @@ -1189,6 +1189,7 @@ impl From<&CFDictionary> for WindowBounds { #[derive(Copy, Clone, Debug, Display, EnumString, Serialize, Deserialize, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] #[serde(untagged)] +/// Aspect ratio for temporarily floating windows pub enum AspectRatio { /// A predefined aspect ratio Predefined(PredefinedAspectRatio), @@ -1204,6 +1205,7 @@ impl Default for AspectRatio { #[derive(Copy, Clone, Debug, Default, Display, EnumString, Serialize, Deserialize, PartialEq)] #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +/// Predefined aspect ratio pub enum PredefinedAspectRatio { /// 21:9 Ultrawide, diff --git a/nix/komorebi-bar-options.nix b/nix/komorebi-bar-options.nix index 7ca7ba89..e75094b0 100644 --- a/nix/komorebi-bar-options.nix +++ b/nix/komorebi-bar-options.nix @@ -867,15 +867,19 @@ in options = { bottom = lib.mkOption { type = lib.types.int; + description = "Height of the rectangle (from the top point)"; }; left = lib.mkOption { type = lib.types.int; + description = "Left point of the rectangle"; }; right = lib.mkOption { type = lib.types.int; + description = "Width of the recentangle (from the left point)"; }; top = lib.mkOption { type = lib.types.int; + description = "Top point of the rectangle"; }; }; } @@ -935,6 +939,39 @@ in ] ); }; + auto_select_text = lib.mkOption { + type = ( + lib.types.nullOr ( + lib.types.oneOf [ + (lib.types.nullOr catppuccinValue) + (lib.types.nullOr base16Value) + ] + ) + ); + default = null; + }; + auto_select_fill = lib.mkOption { + type = ( + lib.types.nullOr ( + lib.types.oneOf [ + (lib.types.nullOr catppuccinValue) + (lib.types.nullOr base16Value) + ] + ) + ); + default = null; + }; + accent = lib.mkOption { + type = ( + lib.types.nullOr ( + lib.types.oneOf [ + (lib.types.nullOr catppuccinValue) + (lib.types.nullOr base16Value) + ] + ) + ); + default = null; + }; name = lib.mkOption { type = ( lib.types.nullOr ( @@ -1280,39 +1317,6 @@ in ); default = null; }; - auto_select_text = lib.mkOption { - type = ( - lib.types.nullOr ( - lib.types.oneOf [ - (lib.types.nullOr catppuccinValue) - (lib.types.nullOr base16Value) - ] - ) - ); - default = null; - }; - accent = lib.mkOption { - type = ( - lib.types.nullOr ( - lib.types.oneOf [ - (lib.types.nullOr catppuccinValue) - (lib.types.nullOr base16Value) - ] - ) - ); - default = null; - }; - auto_select_fill = lib.mkOption { - type = ( - lib.types.nullOr ( - lib.types.oneOf [ - (lib.types.nullOr catppuccinValue) - (lib.types.nullOr base16Value) - ] - ) - ); - default = null; - }; }; } ) diff --git a/nix/komorebi-options.nix b/nix/komorebi-options.nix index a2c28d79..80e4f26a 100644 --- a/nix/komorebi-options.nix +++ b/nix/komorebi-options.nix @@ -140,6 +140,7 @@ let options = { id = lib.mkOption { type = lib.types.str; + description = "Target identifier"; }; kind = lib.mkOption { type = ( @@ -150,6 +151,7 @@ let "Path" ] ); + description = "Kind of identifier to target"; }; matching_strategy = lib.mkOption { type = ( @@ -169,6 +171,7 @@ let ) ); default = null; + description = "Matching strategy to use"; }; }; } @@ -192,15 +195,19 @@ let options = { bottom = lib.mkOption { type = lib.types.int; + description = "Height of the rectangle (from the top point)"; }; left = lib.mkOption { type = lib.types.int; + description = "Left point of the rectangle"; }; right = lib.mkOption { type = lib.types.int; + description = "Width of the recentangle (from the left point)"; }; top = lib.mkOption { type = lib.types.int; + description = "Top point of the rectangle"; }; }; } @@ -759,6 +766,17 @@ in ); default = null; }; + unfocused_locked_border = lib.mkOption { + type = ( + lib.types.nullOr ( + lib.types.oneOf [ + (lib.types.nullOr catppuccinValue) + (lib.types.nullOr base16Value) + ] + ) + ); + default = null; + }; stack_border = lib.mkOption { type = ( lib.types.nullOr ( @@ -770,6 +788,28 @@ in ); default = null; }; + floating_border = lib.mkOption { + type = ( + lib.types.nullOr ( + lib.types.oneOf [ + (lib.types.nullOr catppuccinValue) + (lib.types.nullOr base16Value) + ] + ) + ); + default = null; + }; + unfocused_border = lib.mkOption { + type = ( + lib.types.nullOr ( + lib.types.oneOf [ + (lib.types.nullOr catppuccinValue) + (lib.types.nullOr base16Value) + ] + ) + ); + default = null; + }; colours = lib.mkOption { type = ( lib.types.nullOr ( @@ -829,17 +869,6 @@ in ); default = null; }; - unfocused_border = lib.mkOption { - type = ( - lib.types.nullOr ( - lib.types.oneOf [ - (lib.types.nullOr catppuccinValue) - (lib.types.nullOr base16Value) - ] - ) - ); - default = null; - }; monocle_border = lib.mkOption { type = ( lib.types.nullOr ( @@ -851,7 +880,7 @@ in ); default = null; }; - floating_border = lib.mkOption { + bar_accent = lib.mkOption { type = ( lib.types.nullOr ( lib.types.oneOf [ @@ -1148,34 +1177,12 @@ in ); default = null; }; - unfocused_locked_border = lib.mkOption { - type = ( - lib.types.nullOr ( - lib.types.oneOf [ - (lib.types.nullOr catppuccinValue) - (lib.types.nullOr base16Value) - ] - ) - ); - default = null; - }; - bar_accent = lib.mkOption { - type = ( - lib.types.nullOr ( - lib.types.oneOf [ - (lib.types.nullOr catppuccinValue) - (lib.types.nullOr base16Value) - ] - ) - ); - default = null; - }; }; } ) ); default = null; - description = "Theme configuration options"; + description = "Theme configuration options\n\nIf a theme is specified, `border_colours` will have no effect"; }; toggle_float_placement = lib.mkOption { type = (lib.types.nullOr placement); diff --git a/schema.asc.json b/schema.asc.json index 24b49e77..e5844e94 100644 --- a/schema.asc.json +++ b/schema.asc.json @@ -7,12 +7,28 @@ }, "$defs": { "ApplicationIdentifier": { - "type": "string", - "enum": [ - "Exe", - "Class", - "Title", - "Path" + "description": "Application identifier", + "oneOf": [ + { + "description": "Executable name", + "type": "string", + "const": "Exe" + }, + { + "description": "Role or subrole", + "type": "string", + "const": "Class" + }, + { + "description": "Window title", + "type": "string", + "const": "Title" + }, + { + "description": "Executable path", + "type": "string", + "const": "Path" + } ] }, "AscApplicationRules": { @@ -112,15 +128,19 @@ ] }, "IdWithIdentifier": { + "description": "Rule for matching applications", "type": "object", "properties": { "id": { + "description": "Target identifier", "type": "string" }, "kind": { + "description": "Kind of identifier to target", "$ref": "#/$defs/ApplicationIdentifier" }, "matching_strategy": { + "description": "Matching strategy to use", "anyOf": [ { "$ref": "#/$defs/MatchingStrategy" @@ -137,11 +157,14 @@ ] }, "MatchingRule": { + "description": "Rule for matching applications", "anyOf": [ { + "description": "Simple matching rule which must evaluate to true", "$ref": "#/$defs/IdWithIdentifier" }, { + "description": "Composite matching rule where all conditions must evaluate to true", "type": "array", "items": { "$ref": "#/$defs/IdWithIdentifier" @@ -150,18 +173,58 @@ ] }, "MatchingStrategy": { - "type": "string", - "enum": [ - "Legacy", - "Equals", - "StartsWith", - "EndsWith", - "Contains", - "Regex", - "DoesNotEndWith", - "DoesNotStartWith", - "DoesNotEqual", - "DoesNotContain" + "description": "Strategy for matching identifiers", + "oneOf": [ + { + "description": "Should not be used, only kept for backward compatibility", + "type": "string", + "const": "Legacy" + }, + { + "description": "Equals", + "type": "string", + "const": "Equals" + }, + { + "description": "Starts With", + "type": "string", + "const": "StartsWith" + }, + { + "description": "Ends With", + "type": "string", + "const": "EndsWith" + }, + { + "description": "Contains", + "type": "string", + "const": "Contains" + }, + { + "description": "Regex", + "type": "string", + "const": "Regex" + }, + { + "description": "Does not end with", + "type": "string", + "const": "DoesNotEndWith" + }, + { + "description": "Does not start with", + "type": "string", + "const": "DoesNotStartWith" + }, + { + "description": "Does not equal", + "type": "string", + "const": "DoesNotEqual" + }, + { + "description": "Does not contain", + "type": "string", + "const": "DoesNotContain" + } ] } } diff --git a/schema.bar.json b/schema.bar.json index 04cf58d8..26db7f9a 100644 --- a/schema.bar.json +++ b/schema.bar.json @@ -901,17 +901,54 @@ ] }, "DefaultLayout": { - "type": "string", - "enum": [ - "BSP", - "Columns", - "Rows", - "VerticalStack", - "HorizontalStack", - "UltrawideVerticalStack", - "Grid", - "RightMainVerticalStack", - "Scrolling" + "description": "A predefined komorebi layout", + "default": "BSP", + "oneOf": [ + { + "description": "BSP Layout\n\n```\n+-------+-----+\n| | |\n| +--+--+\n| | |--|\n+-------+--+--+\n```", + "type": "string", + "const": "BSP" + }, + { + "description": "Columns Layout\n\n```\n+--+--+--+--+\n| | | | |\n| | | | |\n| | | | |\n+--+--+--+--+\n```", + "type": "string", + "const": "Columns" + }, + { + "description": "Rows Layout\n\n```\n+-----------+\n|-----------|\n|-----------|\n|-----------|\n+-----------+\n```", + "type": "string", + "const": "Rows" + }, + { + "description": "Vertical Stack Layout\n\n```\n+-------+-----+\n| | |\n| +-----+\n| | |\n+-------+-----+\n```", + "type": "string", + "const": "VerticalStack" + }, + { + "description": "Horizontal Stack Layout\n\n```\n+------+------+\n| |\n|------+------+\n| | |\n+------+------+\n```", + "type": "string", + "const": "HorizontalStack" + }, + { + "description": "Ultrawide Vertical Stack Layout\n\n```\n+-----+-----------+-----+\n| | | |\n| | +-----+\n| | | |\n| | +-----+\n| | | |\n+-----+-----------+-----+\n```", + "type": "string", + "const": "UltrawideVerticalStack" + }, + { + "description": "Grid Layout\n\n```\n+-----+-----+ +---+---+---+ +---+---+---+ +---+---+---+\n| | | | | | | | | | | | | | |\n| | | | | | | | | | | | | +---+\n+-----+-----+ | +---+---+ +---+---+---+ +---+---| |\n| | | | | | | | | | | | | +---+\n| | | | | | | | | | | | | | |\n+-----+-----+ +---+---+---+ +---+---+---+ +---+---+---+\n 4 windows 5 windows 6 windows 7 windows\n```", + "type": "string", + "const": "Grid" + }, + { + "description": "Right Main Vertical Stack Layout\n\n```\n+-----+-------+\n| | |\n+-----+ |\n| | |\n+-----+-------+\n```", + "type": "string", + "const": "RightMainVerticalStack" + }, + { + "description": "Scrolling Layout\n\n```\n+--+--+--+--+--+--+\n| | | |\n| | | |\n| | | |\n+--+--+--+--+--+--+\n```", + "type": "string", + "const": "Scrolling" + } ] }, "DisplayFormat": { @@ -1844,21 +1881,26 @@ } }, "Rect": { + "description": "Rectangle dimensions", "type": "object", "properties": { "bottom": { + "description": "Height of the rectangle (from the top point)", "type": "integer", "format": "int32" }, "left": { + "description": "Left point of the rectangle", "type": "integer", "format": "int32" }, "right": { + "description": "Width of the recentangle (from the left point)", "type": "integer", "format": "int32" }, "top": { + "description": "Top point of the rectangle", "type": "integer", "format": "int32" } diff --git a/schema.json b/schema.json index caeb99c1..20df46a4 100644 --- a/schema.json +++ b/schema.json @@ -261,7 +261,7 @@ "default": 50 }, "theme": { - "description": "Theme configuration options", + "description": "Theme configuration options\n\nIf a theme is specified, `border_colours` will have no effect", "anyOf": [ { "$ref": "#/$defs/KomorebiTheme" @@ -310,44 +310,165 @@ }, "$defs": { "AnimationStyle": { + "description": "Mathematical function which describes the rate at which a value changes", "oneOf": [ { + "description": "Linear", "type": "string", - "enum": [ - "Linear", - "EaseInSine", - "EaseOutSine", - "EaseInOutSine", - "EaseInQuad", - "EaseOutQuad", - "EaseInOutQuad", - "EaseInCubic", - "EaseOutCubic", - "EaseInOutCubic", - "EaseInQuart", - "EaseOutQuart", - "EaseInOutQuart", - "EaseInQuint", - "EaseOutQuint", - "EaseInOutQuint", - "EaseInExpo", - "EaseOutExpo", - "EaseInOutExpo", - "EaseInCirc", - "EaseOutCirc", - "EaseInOutCirc", - "EaseInBack", - "EaseOutBack", - "EaseInOutBack", - "EaseInElastic", - "EaseOutElastic", - "EaseInOutElastic", - "EaseInBounce", - "EaseOutBounce", - "EaseInOutBounce" - ] + "const": "Linear" }, { + "description": "Ease in sine", + "type": "string", + "const": "EaseInSine" + }, + { + "description": "Ease out sine", + "type": "string", + "const": "EaseOutSine" + }, + { + "description": "Ease in out sine", + "type": "string", + "const": "EaseInOutSine" + }, + { + "description": "Ease in quad", + "type": "string", + "const": "EaseInQuad" + }, + { + "description": "Ease out quad", + "type": "string", + "const": "EaseOutQuad" + }, + { + "description": "Ease in out quad", + "type": "string", + "const": "EaseInOutQuad" + }, + { + "description": "Ease in cubic", + "type": "string", + "const": "EaseInCubic" + }, + { + "description": "Ease out cubic", + "type": "string", + "const": "EaseOutCubic" + }, + { + "description": "Ease in out cubic", + "type": "string", + "const": "EaseInOutCubic" + }, + { + "description": "Ease in quart", + "type": "string", + "const": "EaseInQuart" + }, + { + "description": "Ease out quart", + "type": "string", + "const": "EaseOutQuart" + }, + { + "description": "Ease in out quart", + "type": "string", + "const": "EaseInOutQuart" + }, + { + "description": "Ease in quint", + "type": "string", + "const": "EaseInQuint" + }, + { + "description": "Ease out quint", + "type": "string", + "const": "EaseOutQuint" + }, + { + "description": "Ease in out quint", + "type": "string", + "const": "EaseInOutQuint" + }, + { + "description": "Ease in expo", + "type": "string", + "const": "EaseInExpo" + }, + { + "description": "Ease out expo", + "type": "string", + "const": "EaseOutExpo" + }, + { + "description": "Ease in out expo", + "type": "string", + "const": "EaseInOutExpo" + }, + { + "description": "Ease in circ", + "type": "string", + "const": "EaseInCirc" + }, + { + "description": "Ease out circ", + "type": "string", + "const": "EaseOutCirc" + }, + { + "description": "Ease in out circ", + "type": "string", + "const": "EaseInOutCirc" + }, + { + "description": "Ease in back", + "type": "string", + "const": "EaseInBack" + }, + { + "description": "Ease out back", + "type": "string", + "const": "EaseOutBack" + }, + { + "description": "Ease in out back", + "type": "string", + "const": "EaseInOutBack" + }, + { + "description": "Ease in elastic", + "type": "string", + "const": "EaseInElastic" + }, + { + "description": "Ease out elastic", + "type": "string", + "const": "EaseOutElastic" + }, + { + "description": "Ease in out elastic", + "type": "string", + "const": "EaseInOutElastic" + }, + { + "description": "Ease in bounce", + "type": "string", + "const": "EaseInBounce" + }, + { + "description": "Ease out bounce", + "type": "string", + "const": "EaseOutBounce" + }, + { + "description": "Ease in out bounce", + "type": "string", + "const": "EaseInOutBounce" + }, + { + "description": "Custom Cubic Bézier function", "type": "object", "properties": { "CubicBezier": { @@ -382,6 +503,7 @@ ] }, "AnimationsConfig": { + "description": "Animation configuration", "type": "object", "properties": { "duration": { @@ -429,6 +551,7 @@ ] }, "AppSpecificConfigurationPath": { + "description": "Path(s) to application-specific configuration file(s)", "anyOf": [ { "description": "A single applications.json file", @@ -444,15 +567,32 @@ ] }, "ApplicationIdentifier": { - "type": "string", - "enum": [ - "Exe", - "Class", - "Title", - "Path" + "description": "Application identifier", + "oneOf": [ + { + "description": "Executable name", + "type": "string", + "const": "Exe" + }, + { + "description": "Role or subrole", + "type": "string", + "const": "Class" + }, + { + "description": "Window title", + "type": "string", + "const": "Title" + }, + { + "description": "Executable path", + "type": "string", + "const": "Path" + } ] }, "AspectRatio": { + "description": "Aspect ratio for temporarily floating windows", "anyOf": [ { "description": "A predefined aspect ratio", @@ -477,11 +617,23 @@ ] }, "Axis": { - "type": "string", - "enum": [ - "Horizontal", - "Vertical", - "HorizontalAndVertical" + "description": "An axis on which to perform an operation", + "oneOf": [ + { + "description": "Horizontal axis", + "type": "string", + "const": "Horizontal" + }, + { + "description": "Vertical axis", + "type": "string", + "const": "Vertical" + }, + { + "description": "Both horizontal and vertical axes", + "type": "string", + "const": "HorizontalAndVertical" + } ] }, "Base16": { @@ -851,6 +1003,7 @@ ] }, "BorderColours": { + "description": "Border colours for different container states\n\nThese options will have no effect if a `theme` is set", "type": "object", "properties": { "floating": { @@ -974,6 +1127,7 @@ ] }, "CrossBoundaryBehaviour": { + "description": "Behaviour when an action would cross a monitor boundary", "oneOf": [ { "description": "Attempt to perform actions across a workspace boundary", @@ -988,20 +1142,58 @@ ] }, "DefaultLayout": { - "type": "string", - "enum": [ - "BSP", - "Columns", - "Rows", - "VerticalStack", - "HorizontalStack", - "UltrawideVerticalStack", - "Grid", - "RightMainVerticalStack", - "Scrolling" + "description": "A predefined komorebi layout", + "default": "BSP", + "oneOf": [ + { + "description": "BSP Layout\n\n```\n+-------+-----+\n| | |\n| +--+--+\n| | |--|\n+-------+--+--+\n```", + "type": "string", + "const": "BSP" + }, + { + "description": "Columns Layout\n\n```\n+--+--+--+--+\n| | | | |\n| | | | |\n| | | | |\n+--+--+--+--+\n```", + "type": "string", + "const": "Columns" + }, + { + "description": "Rows Layout\n\n```\n+-----------+\n|-----------|\n|-----------|\n|-----------|\n+-----------+\n```", + "type": "string", + "const": "Rows" + }, + { + "description": "Vertical Stack Layout\n\n```\n+-------+-----+\n| | |\n| +-----+\n| | |\n+-------+-----+\n```", + "type": "string", + "const": "VerticalStack" + }, + { + "description": "Horizontal Stack Layout\n\n```\n+------+------+\n| |\n|------+------+\n| | |\n+------+------+\n```", + "type": "string", + "const": "HorizontalStack" + }, + { + "description": "Ultrawide Vertical Stack Layout\n\n```\n+-----+-----------+-----+\n| | | |\n| | +-----+\n| | | |\n| | +-----+\n| | | |\n+-----+-----------+-----+\n```", + "type": "string", + "const": "UltrawideVerticalStack" + }, + { + "description": "Grid Layout\n\n```\n+-----+-----+ +---+---+---+ +---+---+---+ +---+---+---+\n| | | | | | | | | | | | | | |\n| | | | | | | | | | | | | +---+\n+-----+-----+ | +---+---+ +---+---+---+ +---+---| |\n| | | | | | | | | | | | | +---+\n| | | | | | | | | | | | | | |\n+-----+-----+ +---+---+---+ +---+---+---+ +---+---+---+\n 4 windows 5 windows 6 windows 7 windows\n```", + "type": "string", + "const": "Grid" + }, + { + "description": "Right Main Vertical Stack Layout\n\n```\n+-----+-------+\n| | |\n+-----+ |\n| | |\n+-----+-------+\n```", + "type": "string", + "const": "RightMainVerticalStack" + }, + { + "description": "Scrolling Layout\n\n```\n+--+--+--+--+--+--+\n| | | |\n| | | |\n| | | |\n+--+--+--+--+--+--+\n```", + "type": "string", + "const": "Scrolling" + } ] }, "FloatingLayerBehaviour": { + "description": "Floating layer behaviour when a new window is opened", "oneOf": [ { "description": "Tile new windows (unless they match a float rule or float override is active)", @@ -1016,6 +1208,7 @@ ] }, "GridLayoutOptions": { + "description": "Options for the Grid layout", "type": "object", "properties": { "rows": { @@ -1034,15 +1227,19 @@ "format": "color-hex" }, "IdWithIdentifier": { + "description": "Rule for matching applications", "type": "object", "properties": { "id": { + "description": "Target identifier", "type": "string" }, "kind": { + "description": "Kind of identifier to target", "$ref": "#/$defs/ApplicationIdentifier" }, "matching_strategy": { + "description": "Matching strategy to use", "anyOf": [ { "$ref": "#/$defs/MatchingStrategy" @@ -1059,6 +1256,7 @@ ] }, "KomorebiTheme": { + "description": "Komorebi theme", "oneOf": [ { "description": "A theme from catppuccin-egui", @@ -1369,6 +1567,7 @@ ] }, "LayoutOptions": { + "description": "Options for specific layouts", "type": "object", "properties": { "grid": { @@ -1396,11 +1595,14 @@ } }, "MatchingRule": { + "description": "Rule for matching applications", "anyOf": [ { + "description": "Simple matching rule which must evaluate to true", "$ref": "#/$defs/IdWithIdentifier" }, { + "description": "Composite matching rule where all conditions must evaluate to true", "type": "array", "items": { "$ref": "#/$defs/IdWithIdentifier" @@ -1409,21 +1611,62 @@ ] }, "MatchingStrategy": { - "type": "string", - "enum": [ - "Legacy", - "Equals", - "StartsWith", - "EndsWith", - "Contains", - "Regex", - "DoesNotEndWith", - "DoesNotStartWith", - "DoesNotEqual", - "DoesNotContain" + "description": "Strategy for matching identifiers", + "oneOf": [ + { + "description": "Should not be used, only kept for backward compatibility", + "type": "string", + "const": "Legacy" + }, + { + "description": "Equals", + "type": "string", + "const": "Equals" + }, + { + "description": "Starts With", + "type": "string", + "const": "StartsWith" + }, + { + "description": "Ends With", + "type": "string", + "const": "EndsWith" + }, + { + "description": "Contains", + "type": "string", + "const": "Contains" + }, + { + "description": "Regex", + "type": "string", + "const": "Regex" + }, + { + "description": "Does not end with", + "type": "string", + "const": "DoesNotEndWith" + }, + { + "description": "Does not start with", + "type": "string", + "const": "DoesNotStartWith" + }, + { + "description": "Does not equal", + "type": "string", + "const": "DoesNotEqual" + }, + { + "description": "Does not contain", + "type": "string", + "const": "DoesNotContain" + } ] }, "MonitorConfig": { + "description": "Monitor configuration", "type": "object", "properties": { "container_padding": { @@ -1520,6 +1763,7 @@ ] }, "MoveBehaviour": { + "description": "Move behaviour when the operation works across a monitor boundary", "oneOf": [ { "description": "Swap the window container with the window container at the edge of the adjacent monitor", @@ -1539,14 +1783,15 @@ ] }, "OperationBehaviour": { + "description": "Operation behaviour for temporarily unmanaged and floating windows", "oneOf": [ { - "description": "Process komorebic commands on temporarily unmanaged/floated windows", + "description": "Process commands on temporarily unmanaged/floated windows", "type": "string", "const": "Op" }, { - "description": "Ignore komorebic commands on temporarily unmanaged/floated windows", + "description": "Ignore commands on temporarily unmanaged/floated windows", "type": "string", "const": "NoOp" } @@ -1556,21 +1801,26 @@ "type": "string" }, "PerAnimationPrefixConfig": { + "description": "Animation configuration\n\nThis can be either global:\n```json\n{\n \"enabled\": true,\n \"style\": \"EaseInSine\",\n \"fps\": 60,\n \"duration\": 250\n}\n```\n\nOr scoped by an animation kind prefix:\n```json\n{\n \"movement\": {\n \"enabled\": true,\n \"style\": \"EaseInSine\",\n \"fps\": 60,\n \"duration\": 250\n }\n}\n```", "anyOf": [ { + "description": "Animation configuration prefixed for a specific animation kind", "type": "object", "additionalProperties": { "type": "boolean" } }, { + "description": "Animation configuration for all animation kinds", "type": "boolean" } ] }, "PerAnimationPrefixConfig2": { + "description": "Animation configuration\n\nThis can be either global:\n```json\n{\n \"enabled\": true,\n \"style\": \"EaseInSine\",\n \"fps\": 60,\n \"duration\": 250\n}\n```\n\nOr scoped by an animation kind prefix:\n```json\n{\n \"movement\": {\n \"enabled\": true,\n \"style\": \"EaseInSine\",\n \"fps\": 60,\n \"duration\": 250\n }\n}\n```", "anyOf": [ { + "description": "Animation configuration prefixed for a specific animation kind", "type": "object", "additionalProperties": { "type": "integer", @@ -1579,6 +1829,7 @@ } }, { + "description": "Animation configuration for all animation kinds", "type": "integer", "format": "uint64", "minimum": 0 @@ -1586,19 +1837,23 @@ ] }, "PerAnimationPrefixConfig3": { + "description": "Animation configuration\n\nThis can be either global:\n```json\n{\n \"enabled\": true,\n \"style\": \"EaseInSine\",\n \"fps\": 60,\n \"duration\": 250\n}\n```\n\nOr scoped by an animation kind prefix:\n```json\n{\n \"movement\": {\n \"enabled\": true,\n \"style\": \"EaseInSine\",\n \"fps\": 60,\n \"duration\": 250\n }\n}\n```", "anyOf": [ { + "description": "Animation configuration prefixed for a specific animation kind", "type": "object", "additionalProperties": { "$ref": "#/$defs/AnimationStyle" } }, { + "description": "Animation configuration for all animation kinds", "$ref": "#/$defs/AnimationStyle" } ] }, "Placement": { + "description": "Placement behaviour for floating windows", "oneOf": [ { "description": "Does not change the size or position of the window", @@ -1618,6 +1873,7 @@ ] }, "PredefinedAspectRatio": { + "description": "Predefined aspect ratio", "oneOf": [ { "description": "21:9", @@ -1637,21 +1893,26 @@ ] }, "Rect": { + "description": "Rectangle dimensions", "type": "object", "properties": { "bottom": { + "description": "Height of the rectangle (from the top point)", "type": "integer", "format": "int32" }, "left": { + "description": "Left point of the rectangle", "type": "integer", "format": "int32" }, "right": { + "description": "Width of the recentangle (from the left point)", "type": "integer", "format": "int32" }, "top": { + "description": "Top point of the rectangle", "type": "integer", "format": "int32" } @@ -1692,6 +1953,7 @@ ] }, "ScrollingLayoutOptions": { + "description": "Options for the Scrolling layout", "type": "object", "properties": { "center_focused_column": { @@ -1713,6 +1975,7 @@ ] }, "ThemeOptions": { + "description": "Theme options", "type": "object", "properties": { "bar_accent": { @@ -1821,6 +2084,7 @@ ] }, "Wallpaper": { + "description": "Wallpaper configuration", "type": "object", "properties": { "generate_theme": { @@ -1852,6 +2116,7 @@ ] }, "WindowContainerBehaviour": { + "description": "Window container behaviour when a new window is opened", "oneOf": [ { "description": "Create a new container for each new window", @@ -1880,6 +2145,7 @@ ] }, "WorkspaceConfig": { + "description": "Workspace configuration", "type": "object", "properties": { "apply_window_based_work_area_offset": {