Refactor UltraLegend builder into dedicated module

[cvanelteren]

This draft PR extracts the axes legend construction flow into a dedicated UltraLegend builder module to reduce complexity in Axes._add_legend, centralize input normalization/layout/style application, and improve maintainability while preserving existing behavior. It also adds targeted legend tests around panel span inference and placement edge cases to guard the refactor. Follow-up to #529.

[gepcel]

I saw you are refactoring legend handlings, is there any change you can make some public helper function or construct function like the way legendkit deos? Though legend handling is more convince in ultraplot than matplotlib, sometime manually construct a legend is still needed.

For example, I usually use legendkit to generate a legend, but it's not totally compatible with cartopy (or ultraplot, i'm not sure).

from legendkit import legend
fig,ax=pplt.subplot(proj='cyl')
g = gpd.read_file(r'some_example_shapefile.shp')
ax.add_geometries(g.geometry, crs=pcrs, label='LabelNameOfSomething')
# ax.legend() #doesn't work
legend(legend_items=[
  ('rect', 'LabelNameOfSomething', {'fc': 'r', 'alpha':0.7}),
  ('circle', "OtherPlace', {'fc': 'none', 'ec': 'blue'})
], loc='lower left', title='Legend')

[cvanelteren]

Oh cool! I was not aware of this package. Can you elaborate a bit more on what your snippet does that we cannot right now?

[gepcel]

It has a very simple, very useful document, provide several examples, would you mind checkout webpage: https://legendkit.readthedocs.io/en/latest/tutorial/legend.html

[cvanelteren]

Ah this is similar to what I wanted to achieve with #571

[gepcel]

Ah this is similar to what I wanted to achieve with #571

Yeah, I was kind of wishing you may borrow some ideas from legendkit after I saw what you did in #571

[cvanelteren]

I can see if I can work this into that PR. This one is merely decoupling the logic that within base.py to make the backend more easy to manage. Some of the files are rather large with functions that could be improved by decoupling the logic and simplifying it.

Will give this some thought how to make it more flexible.

[cvanelteren]

Ok I think after we merge #570 and #571 I can put this on the docket to add semantic legend creation.

[gepcel]

Thanks, it will be very useful.