zsh: respect xdg.enable for dotDir

Make sure we actually respect a user's `xdg.enable` preference.

Signed-off-by: Austin Horstman <khaneliman12@gmail.com>

docs/release-notes/rl-2605.md

@@ -15,3 +15,7 @@ changes are only active if the `home.stateVersion` option is set to
 
 - The `gtk.gtk4.theme` option does not mirror `gtk.theme` by default
   anymore.
+
+- The `programs.zsh.dotDir` option now defaults to the XDG configuration
+  directory (usually `~/.config/zsh`) when `xdg.enable` is true.
+

modules/programs/zsh/default.nix

@@ -2,6 +2,7 @@
   config,
   lib,
   pkgs,
+  options,
   ...
 }:
 let
@@ -100,8 +101,17 @@ in
         };
 
         dotDir = mkOption {
-          default = homeDir;
-          defaultText = "`config.home.homeDirectory`";
+          default =
+            if config.xdg.enable && lib.versionAtLeast config.home.stateVersion "26.05" then
+              "${config.xdg.configHome}/zsh"
+            else
+              homeDir;
+          defaultText = lib.literalExpression ''
+            if config.xdg.enable && lib.versionAtLeast config.home.stateVersion "26.05" then
+              "''${config.xdg.configHome}/zsh"
+            else
+              config.home.homeDirectory
+          '';
           example = "`\${config.xdg.configHome}/zsh`";
           description = ''
             Directory where the zsh configuration and more should be located,
@@ -391,7 +401,24 @@ in
                   - config.xdg.dataHome (XDG data directory)
                   - config.xdg.cacheHome (XDG cache directory)
                 ''
-              ];
+              ]
+            ++
+              lib.optionals
+                (
+                  config.xdg.enable
+                  && !lib.versionAtLeast config.home.stateVersion "26.05"
+                  && options.programs.zsh.dotDir.highestPrio >= 1500
+                )
+                [
+                  ''
+                    The default value of `programs.zsh.dotDir` will change in future versions.
+                    You are currently using the legacy default (home directory) because `home.stateVersion` is less than "26.05".
+                    To silence this warning and lock in the current behavior, set:
+                      programs.zsh.dotDir = config.home.homeDirectory;
+                    To adopt the new behavior (XDG config directory), update `home.stateVersion` to "26.05" or set:
+                      programs.zsh.dotDir = "''${config.xdg.configHome}/zsh";
+                  ''
+                ];
         }
 
         (mkIf (cfg.envExtra != "") {
@@ -420,7 +447,7 @@ in
           # already set correctly (by e.g. spawning a zsh inside a zsh), all env
           # vars still get exported
           home.file.".zshenv".text = ''
-            source "${dotDirAbs}/.zshenv"
+            source ${lib.escapeShellArg "${dotDirAbs}/.zshenv"}
           '';
         })
 

tests/default.nix

@@ -130,6 +130,13 @@ let
             stateVersion = lib.mkDefault "18.09";
           };
 
+          # NOTE: Added 2025-12-27
+          # Avoid option change deprecation warning
+          # Remove after deprecation period
+          programs.zsh.dotDir = lib.mkIf (config.home.stateVersion == "18.09") (
+            lib.mkDefault "/home/hm-user"
+          );
+
           # Avoid including documentation since this will cause
           # unnecessary rebuilds of the tests.
           manual.manpages.enable = lib.mkDefault false;

tests/modules/programs/zsh/dotdir.nix

@@ -99,7 +99,7 @@ in
           "assertFileExists 'home-files/${if relDotDir == "" then "" else "${relDotDir}/"}.zshenv'"
 
           # for non-default dotDir only:
-          (lib.optionalString (case != "default" && case != "root-slash" && case != "root-no-slash") ''
+          (lib.optionalString (absDotDir != home) ''
             # check .zshenv in homeDirectory sources .zshenv in dotDir
             assertFileRegex home-files/.zshenv "source ${lib.escapeShellArg "${absDotDir}/.zshenv"}"