Multipart autocomplete, zstyle, and cd

[Zach Riggle <zachriggle@gmail.com>]

I would like to add a new autocomplete section to the tab-completion
of "cd".  I have some of the pieces of this working, but haven't
figured out how to hook it up correctly.

#-------------------------------- BACKGROUND ---------------------------------
I have a zsh autoloadable function, zshz-cd-completion.  Its
implementation is not relevant, except that it outputs a list of
directory names in a specific order.

For now, let's assume zsh-cd-completion emits the following lines:

    Downloads/
    bin/
    Library/
    Desktop/

#-------------------------------- COMPLETION ---------------------------------
I have completion working for a placeholder command, foobarbaz.  This
is done with a file, _foobarbaz, also in $fpath.  It is very
straightforward, and works as intended.

    #compdef foobarbaz

    _arguments \
        '*: :->custom'

    case "$state" in
        custom)
            local -a dirs=( $(zshz-cd-completion) )

            # Old: Does not preserve ordering
            # _values "popular directories" $dirs

            _wanted -V popular-directories expl 'popular directories' \
                compadd -Q -a dirs
            ;;
    esac

#-------------------------- COMPLETION ENHANCEMENT ---------------------------
This completion works well, though I would like to know how to get the
completion to not do word-separated completion and upon e.g.

    $ foobarbaz bi<tab>

Turns into...

    $ foobarbaz bin/

... to not add a space, but instead allow further specification e.g.,

    $ foobarbaz bin/subdir

#-------------------------- CURRENT CD AUTOCOMPLETE --------------------------
I would like to know how to get these results added to "cd"
autocompletion.  I expect that I can do this from zstyle.  Currently,
this is how things are configured:

    $ zstyle -L | grep :cd:
    zstyle ':completion:*:*:cd:*:directory-stack' menu yes select
    zstyle ':completion:*:*:cd:*' tag-order local-directories
directory-stack path-directories

When I do "cd <tab>", I get a single section, "-- local directory --".

#-------------------------- ADDING A SECTION TO CD ---------------------------
I tried my very best to comprehend Section 20 "Completion System" of
the documentation, and various other distillations on Github and so on
-- but this is the most complex documentation I've come across, and
the various "magic" that powers it is too complex to read through.

Any pointers would be useful -- it's not clear if I need to define a
new tag somehow (via _tags?) or modify the _cd function and put my
modified copy earlier in $fpath.  I hope / expect that this is
something that can be MOSTLY achieved via zstyle, but I'm not clear
how.

Zach Riggle