Actions - Availability Helpers

[benjamin-kirkbride]

Subtask of #1342

I wanted to document the different ideas that have been had for availability helpers (formerly known as availability callbacks).

Discussion here about how we came to the current design: #1349 (comment)

Discussion here about how we need to be sure to document well the different patterns and helpers: #1349 (comment)

List of helpers to be made/ironed out:

• filetype of tab
• filetype of file
• name of file
• if a Path is the "project root"
• if a Path is .gitignore'd
• contents of the FileTab selection
• contents of the FileTab insert line
• contents of the clipboard
• whether a FileTab has unsaved changes
• contents of the Filetab undo stack
• if internet is available
• various config options
• if plugins are available

[benjamin-kirkbride]

For posterity this was the (bad) design for the filetype_availability helper

def filetype_availability(filetypes: list[str]) -> Callable[[FileTab | Path], bool]:
    def _filetype_availability(filetypes: list[str], context: FileTab | Path) -> bool:
        if isinstance(context, FileTab):
            tab = context
            if tab.settings.get("filetype_name", object) in filetypes:
                return True
            return False

        if isinstance(context, Path):
            path = context

            if not path.exists():
                raise RuntimeError(f"{path} does not exist.")
            if path.is_dir():
                raise RuntimeError(
                    f"{path} is a directory - an action consumer registered this action incorrectly"
                )
            if not path.is_file():
                raise RuntimeError(f"{path} is not a file")

            # return True if get_filetype_from_path(path) in filetypes else False
            raise NotImplementedError  # TODO: there is a way to do this already right?

        raise RuntimeError("wrong context passed")

    return partial(_filetype_availability, filetypes)