Revert "JS: Delete spacemacs-purpose layer"

This reverts commit 1c8b01a.

layers/+distributions/spacemacs/layers.el

@@ -41,5 +41,6 @@
    spacemacs-navigation
    spacemacs-org
    spacemacs-project
+   spacemacs-purpose
    spacemacs-visual
    ))

layers/+spacemacs/spacemacs-purpose/README.org

@@ -0,0 +1,152 @@
+#+TITLE: Spacemacs-purpose layer
+
+#+TAGS: layer|misc|spacemacs
+
+* Table of Contents                     :TOC_5_gh:noexport:
+- [[#description][Description]]
+  - [[#features][Features:]]
+- [[#purposes][Purposes]]
+  - [[#switch-to-buffer-and-display-buffer][switch-to-buffer and display-buffer]]
+  - [[#misc][misc]]
+- [[#install][Install]]
+- [[#usage][Usage]]
+  - [[#allocate-purposes-in-layers][Allocate purposes in layers]]
+  - [[#overwrite-purposes-in-dotfile][Overwrite purposes in dotfile]]
+- [[#key-bindings][Key bindings]]
+- [[#caveats][Caveats]]
+  - [[#popwin-and-guide-key][Popwin and guide-key]]
+  - [[#packages-that-do-display-management][Packages that do display management]]
+
+* Description
+This layer enables [[https://github.com/bmag/emacs-purpose][window-purpose]], which provides an alternative, purpose-based
+window manager for Emacs. With this layer, your window layout should be robust
+and shouldn't change too much when opening all sorts of buffers.
+
+Regular [[https://github.com/m2ym/popwin-el][popwin]] is not triggered when window-purpose is enabled. However,
+the window-purpose layer provides a =purpose-popwin= extension, which
+brings popwin's behavior to window-purpose and solves that problem.
+
+** Features:
+- Window layout is more robust and less likely to change unintentionally
+- Dedicate window to a purpose
+- User-defined purposes
+- Extensible window display behavior
+- Empty =purpose-mode-map=, to avoid conflicts with other key maps
+- Replicate popwin behavior for purpose-mode - almost no regression in popup behavior from using window-purpose.
+- Reuses popwin's settings: =popwin:special-display-config=, =popwin:popup-window-height= and =popwin:popup-window-width=.
+- Difference from popwin: when several windows are open, popup window is sometimes bigger than with regular popwin in the same situation.
+
+* Purposes
+window-purpose contains a configuration which assigns a purpose for each
+buffer. Later, when Emacs needs to display a buffer in a window, its purpose
+helps make a better decision of which window to use.
+
+For example, consider the following case: Emacs frame shows three windows - one
+for code, one for a terminal and one general-purpose window. The general window
+is selected and you want to open a code file. How do you ensure that the code
+file will be displayed in the code window? With window-purpose you don't
+need to worry about it - you open the file and window-purpose places it in
+the correct window.
+
+Additionally, you can dedicate a window to a purpose - so that window is
+reserved only for buffers that share that purpose.
+
+** switch-to-buffer and display-buffer
+In regular Emacs, =switch-to-buffer= follows different rules than the other
+switching and popping commands, because it doesn't use =display-buffer= (which
+the other commands do). With window-purpose, this behavior is fixed. The
+result is a better control over how buffers are displayed, since
+=switch-to-buffer= doesn't ignore the user's customizations anymore.
+
+** misc
+- specialized helm source similar to =helm-source-buffers-list=
+
+* Install
+To use this configuration layer, add it to your =~/.spacemacs=. You will need to
+add =spacemacs-purpose= to the existing =dotspacemacs-configuration-layers= list in
+this file.
+
+* Usage
+With window-purpose layer installed, =purpose-mode= and =pupo-mode= are enabled.
+You can toggle =purpose-mode= (~SPC : purpose-mode~) at any time to return to
+purpose-less behavior. You can toggle =pupo-mode= (~SPC : pupo-mode~) to turn
+off only the purpose-popwin integration.
+
+If you change =popwin:special-display-config= in your =dotspacemacs/config=, you
+should call =pupo/update-purpose-config= to update purpose-popwin with those
+changes.
+
+See [[https://github.com/bmag/emacs-purpose/wiki][window-purpose wiki]] to learn more about window-purpose.
+
+** Allocate purposes in layers
+Layers may assign purposes to buffers that have been created by their packages.
+This can either be done by a simple mode mapping or according to the buffer's
+name. This follows the same idea as the autocomplete and syntax-checking layers.
+
+This means the configuration is not centralised in this layer but
+spread among the individual language layers. To ensure
+that users can still overwrite these configs it is important
+to declare them uniformly in Spacemacs.
+
+To do so copy and adjust the following code:
+
+#+BEGIN_SRC emacs-lisp
+  ;; This will only be called if `window-purpose` is listed
+  ;; among the layer packages.
+  ;; This code also takes care that the right loading
+  ;; order is followed so there is no need for any
+  ;; `with-eval-after-load` constructs.
+  (defun shell/post-init-window-purpose ()
+    (purpose-set-extension-configuration
+     :shell-layer
+     (purpose-conf :mode-purposes '((vterm-mode . terminal)
+                                    (eshell-mode . terminal)
+                                    (shell-mode . terminal)
+                                    (term-mode . terminal)))))
+     ;; This can also be a static name allocation
+     ;;            :name-purposes '(("*Anaconda Help*" . Help))
+     ;; or a dynamic one following a regexp
+     ;;            :regexp-purposes '(("^\\*Anaconda" . general))
+
+#+END_SRC
+
+** Overwrite purposes in dotfile
+With layers defining all kinds of purposes there will surely
+come the point where one wishes to change one or two of
+these allocations to match ones own personal needs.
+
+This can easily be achieved by adding below code in
+`dotspacemacs/user-config`:
+
+#+BEGIN_SRC emacs-lisp
+  ;; This will add user allocations with a higher
+  ;; priority than the ones from the layers.
+  ;; With this allocations can be completely
+  ;; customised.
+  (purpose-add-user-purposes :names '(("*Anaconda Help*" . general))
+                             :regexps '(("\\.hy$" . python)))
+#+END_SRC
+
+* Key bindings
+
+| Key binding | Description                                                                         |
+|-------------+-------------------------------------------------------------------------------------|
+| ~SPC r b~   | Open a buffer. Only buffers with the same purpose as the current buffer are listed. |
+| ~SPC r B~   | Open any buffer and ignore window-purpose when displaying the buffer.               |
+| ~SPC r d b~ | Toggle dedication of selected window to its current buffer purpose.                 |
+| ~SPC r d w~ | Toggle dedication of selected window to its current purpose.                        |
+| ~SPC r D~   | Delete all non-dedicated windows.                                                   |
+| ~SPC r p~   | Choose a purpose and open a buffer with that purpose.                               |
+| ~SPC r P~   | Change the purpose of the selected window. Changes the window's buffer accordingly. |
+
+* Caveats
+** Popwin and guide-key
+If a buffer is displayed in two different windows, and only one of those windows
+is purpose-dedicated, then invoking guide-key will cause both windows to become
+purpose-dedicated.
+
+** Packages that do display management
+Some packages that manage how windows are displayed, such as =gdb= with
+=gdb-many-windows=, might not play nicely with =window-purpose=. However, it is
+usually possible to find a solution. After all, even =helm= and =popwin= work
+with =window-purpose=.

layers/+spacemacs/spacemacs-purpose/funcs.el

@@ -0,0 +1,74 @@
+;;; funcs.el --- Spacemacs Purpose Layer functions File
+;;
+;; Copyright (c) 2012-2024 Sylvain Benner & Contributors
+;;
+;; Author: Bar Magal
+;; URL: https://github.com/syl20bnr/spacemacs
+;;
+;; This file is not part of GNU Emacs.
+;;
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+;;
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+
+
+;; eyebrowse integration
+
+(defun spacemacs/window-purpose-sync-eyebrowse ()
+  "Synchronize window-purpose layer with eyebrowse.
+Set `eyebrowse-new-workspace' value depending on the state of `purpose-mode'."
+  (defvar spacemacs--window-purpose-eyebrowse-new-workspace
+    eyebrowse-new-workspace
+    "Internal backup of `eyebrowse-new-workspace'.")
+  (require 'window-purpose)
+  (if purpose-mode
+      (setq eyebrowse-new-workspace #'spacemacs//window-purpose-new-workspace)
+    (setq eyebrowse-new-workspace
+          spacemacs--window-purpose-eyebrowse-new-workspace)))
+
+(defun spacemacs//window-purpose-new-workspace ()
+  "Create a new eyebrowse workspace.
+Replacement for `eyebrowse-new-workspace' that handles purpose-dedicated
+windows correctly."
+  ;; call original `eyebrowse-new-workspace' (partially copied from
+  ;; `eyebrowse-switch-to-window-config')
+  (cond
+   ((stringp spacemacs--window-purpose-eyebrowse-new-workspace)
+    (switch-to-buffer (get-buffer-create
+                       spacemacs--window-purpose-eyebrowse-new-workspace)))
+   ((functionp spacemacs--window-purpose-eyebrowse-new-workspace)
+    (funcall spacemacs--window-purpose-eyebrowse-new-workspace))
+   (t (switch-to-buffer "*scratch*")))
+
+  ;; in case opening the new buffer splitted the frame (e.g.
+  ;; `eyebrowse-switch-to-window-config' was called from a purpose-dedicated
+  ;; buffer)
+  (delete-other-windows))
+
+
+;; Popwin integration
+
+(defun spacemacs/window-purpose-sync-popwin ()
+  "Synchronize window-purpose layer with popwin.
+Enable or disable advices to popwin, according to the state of `purpose-mode'."
+  (require 'window-purpose)
+  (if purpose-mode
+      (progn
+        (advice-add #'popwin:create-popup-window
+                    :before #'window-purpose/save-dedicated-windows)
+        (advice-add #'popwin:create-popup-window
+                    :after #'window-purpose/restore-dedicated-windows))
+    (advice-remove #'popwin:create-popup-window
+                   #'window-purpose/save-dedicated-windows)
+    (advice-remove #'popwin:create-popup-window
+                   #'window-purpose/restore-dedicated-windows)))