Icons package and monorepo

[JuroOravec]

I came across this package, cotton-heroicons, that wraps HeroIcons.com icons as django-cotton components.

I use HeroIcons in my work project too, and I too made a component that wraps the icons (see implementation at the end), so I thought I could also package that for others to use.

However, I'm thinking that it would be nice if it could live in this project. I had other projects where there was a lot of small packages that dependend on each other and they lived in different repos, and updating them was always a chore.

Ofc, if it was somebody else, I would probably suggest them to create a separate repo. But since I'm so involved with django-components, then I'm thinking it could be practically like an "officially supported package", and live in django-components repo.

But to make that possible, the repo would have to support monorepo structure.

• One way to achieve that would be to move the root of the project inside src/django_components, and update other bits (like github workflows) accordingly to point to the new path.

• Other, simpler approach, could be to just add a packages directory (e.g. packages/django-components-icons), and put the extra packages there. In that case we'd just need to update github workflows (and maybe dependabot), to pick up also those packages.

I'd go with the second approach for the simplicity, and then one day we could potentially move also the main package.

@EmilStenstrom What do you think?

---

Implementation:

Python

from django_components import Component, register
import components.icon.icons as icons

@register("Icon")
class Icon(Component):
    template_name = "icon.html"

    def get_context_data(
        self,
        /,
        *,
        icon: str,
        size: int | None = 24,
        href: str | None = None,
        color: str | None = "",
        icon_color: str | None = "",
        text_color: str | None = "",
        stroke_width: float | None = 1.5,
        viewbox: str | None = "0 0 24 24",
        text_attrs: dict | None = None,
        link_attrs: dict | None = None,
        svg_attrs: dict | None = None,
        attrs: dict | None = None,
    ):
        # Allow to set icon and text independently, or both at same time via `color` prop
        if not icon_color:
            icon_color = color
        if not text_color:
            text_color = color

        icon_paths = getattr(icons, icon)

        return {
            "href": href,
            "text_color": text_color,
            "icon_color": icon_color,
            "viewbox": viewbox,
            "size": size,
            "stroke_width": stroke_width,
            "text_attrs": text_attrs,
            "link_attrs": link_attrs,
            "svg_attrs": svg_attrs,
            "icon_paths": icon_paths,
            "attrs": attrs,
        }

Django HTML

<div {% html_attrs attrs %}>
  {% if href %}
  <a
    href="{{ href }}"
    {% html_attrs
      link_attrs
      text_attrs
      class=text_color
      class="group flex gap-x-3 rounded-md text-sm leading-6 font-semibold"
    %}
  >
  {% else %}
  <span
    {% html_attrs
      text_attrs
      class=text_color
      class="group flex gap-x-3 rounded-md text-sm leading-6 font-semibold"
    %}
  >
  {% endif %}
    <svg
      fill="none"
      viewBox="{{ viewbox }}"
      stroke-width="{{ stroke_width }}"
      stroke="currentColor"
      aria-hidden="true"
      style="width: {{ size }}px; height: {{ size }}px"
      {% html_attrs
        svg_attrs
        class=icon_color
        class="h-6 w-6 shrink-0"
      %}
    >
      {% for path in icon_paths %}
      <path stroke-linecap="round" stroke-linejoin="round" d="{{ path }}" />
      {% endfor %}
    </svg>

    {% slot "content" default / %}

  {% if href %}
  </a>
  {% else %}
  </span>
  {% endif %}
</div>

[dalito]

Would it make sense to create a django-components organisation under which django-components itself and such component packages are placed?

[JuroOravec]

That would work for me :) not a monorepo, but the packages would be easy to find. @dalito do you know what's the overhead of that, is it easy / hard to set up?

[dalito]

Setting up organizations is simple. If you and Emil should be the owners, then even you could create the organization, make Emil co-owner and he (as owner of this repo) has to transfer this repository. Secure publishing to PyPI would have to be reconfigured for the new repo/URL.

[EmilStenstrom]

Several thoughts:

1. Just because you are the maintainer for both projects right now, that doesn't mean it's that way forever. I'm not sure it's right right model to say that django-components and that specific custom component should be maintained by the same org?
2. We have one generous sponsor for this project. The money is going to my github account which I then redirect to Juro because he's doing all the work. The ideal way would be if this was redirected to the new django-component org, and Juro got it from there, so I don't get the admin of that.
3. What would be awesome is a package repository that you could install from, so as to not have to pip install every single component. Could there be easier ways to administer components? Where would they live?
4. Is this really that different from the special dynamic component? What makes this one different?

[dalito]

On 1: In an organization, repos can have individual maintainers.

I'm was suggesting it as an alternative to think about. Not as a call for action.

3 is a good question. I have not seen alternatives.

[EmilStenstrom]

@dalito Sorry for not being clearer about my tone, I'm just thinking out loud here :)

[JuroOravec]

@EmilStenstrom

1. Fair. Recently I mentally decided to commit to this for another 6-12 months (on part time), instead of pursuing other things, as I want to get this to completion. So to me it can sometimes feel like I will be here forever 😄 But jokes aside, so in that case I'll make the icon component into a separate package and separate repo.

2. I'll leave it up to you to decide how you want to handle this, whether as org or a single repo.

3. I think installing components individually (or however the author of the package grouped them) makes most sense. But what we could definitely do is to make it easier for people to look up packages that provide components for django-components.

   E.g. either in the README or on the website, there could be a list of all known packages that define components for django-components. Similar how e.g. MeteorJS has https://atmospherejs.com/.

   One way how we could find such packages would be to ask authors to prefix their packages with components-, e.g. the icon component would be in a package called components-icon. It could also be django-components- to avoid false positives, but that's already a mouthful.

   Then, at docs site generation, we would programmatically search PyPI for packages that start with that prefix (dunno if possible), and list them on a dedicated page.

   We could do the same for plugins, once those are implemented. Maybe component packages could be prefixed with dc-component- and plugins with dc-plugin-?

   Along the lines of this, we could also have an "awesome-django-components" repo to list all other community things like tutorials and whatnot. Similar to how Vue has https://github.com/vuejs/awesome-vue. This would have to be manually curated.

   For something like "awesome-django-components", IMO it would make sense to live under an organisation.

   ---

   NOTE: Below I explain why I think pip install is currently probably the best way to manage the components. Click to expand

   The issue is that components come with custom Python code, optionally also additional non-Python files. Python packages are made for that.

   If Python had a tree-shaking features, such that you'd download only those parts of a package that you actually import, then in that case it'd be possible to have one large package that contains all components, and one could pick and choose. But that's not the case in Python.

   If the components were purely JS and CSS, then we wouldn't need to load them onto Python / Django, and it'd be as simple as adding a <script> / <link> to the HTML. But components are primarily Python code.

   In some packages like (I think) nltk you can install dependencies via code. However, those dependencies are datasets, so non-Python resources. While we could add a command that'd download a Python file and then import it, it feels like a VeryBadIdea™️ from the security perspective.

   So IMO the code should live as packages.

   As for whether the packages should contain a single components or multiple, the default state is that this is up to the package author. E.g. the icon component would be a single component in a package. But the Vuetify port (Alpinui) would be ~100 components in a single package.

   I don't think we can change anything about that, as the components could be practically arbitrary. IMO only way you could achieve more structure is if you enforced it through a package. E.g. if I had two packages that defined same number of components with same names and same API, then those two packages could be switched freely, and it would be like changing themes. But for that the API would have to be defined first.

4. Sorry, didn't include it, but the icon component also consists of an additional Python file with ~580 lines that define the SVG paths of all the icons:

    # Outline
    outline_academic_cap = ["M4.26 10.147a60.436 60.436 0 00-.491 6.347A48.627 48.627 0 0112 20.904a48.627 48.627 0 018.232-4.41 60.46 60.46 0 00-.491-6.347m-15.482 0a50.57 50.57 0 00-2.658-.813A59.905 59.905 0 0112 3.493a59.902 59.902 0 0110.399 5.84c-.896.248-1.783.52-2.658.814m-15.482 0A50.697 50.697 0 0112 13.489a50.702 50.702 0 017.74-3.342M6.75 15a.75.75 0 100-1.5.75.75 0 000 1.5zm0 0v-3.675A55.378 55.378 0 0112 8.443m-7.007 11.55A5.981 5.981 0 006.75 15.75v-1.5"]
    outline_adjustments_horizontal = ["M10.5 6h9.75M10.5 6a1.5 1.5 0 11-3 0m3 0a1.5 1.5 0 10-3 0M3.75 6H7.5m3 12h9.75m-9.75 0a1.5 1.5 0 01-3 0m3 0a1.5 1.5 0 00-3 0m-3.75 0H7.5m9-6h3.75m-3.75 0a1.5 1.5 0 01-3 0m3 0a1.5 1.5 0 00-3 0m-9.75 0h9.75"]
    outline_adjustments_vertical = ["M6 13.5V3.75m0 9.75a1.5 1.5 0 010 3m0-3a1.5 1.5 0 000 3m0 3.75V16.5m12-3V3.75m0 9.75a1.5 1.5 0 010 3m0-3a1.5 1.5 0 000 3m0 3.75V16.5m-6-9V3.75m0 3.75a1.5 1.5 0 010 3m0-3a1.5 1.5 0 000 3m0 9.75V10.5"]
    outline_archive_box_arrow_down = ["M20.25 7.5l-.625 10.632a2.25 2.25 0 01-2.247 2.118H6.622a2.25 2.25 0 01-2.247-2.118L3.75 7.5m8.25 3v6.75m0 0l-3-3m3 3l3-3M3.375 7.5h17.25c.621 0 1.125-.504 1.125-1.125v-1.5c0-.621-.504-1.125-1.125-1.125H3.375c-.621 0-1.125.504-1.125 1.125v1.5c0 .621.504 1.125 1.125 1.125z"]
    outline_archive_box_x_mark = ["M20.25 7.5l-.625 10.632a2.25 2.25 0 01-2.247 2.118H6.622a2.25 2.25 0 01-2.247-2.118L3.75 7.5m6 4.125l2.25 2.25m0 0l2.25 2.25M12 13.875l2.25-2.25M12 13.875l-2.25 2.25M3.375 7.5h17.25c.621 0 1.125-.504 1.125-1.125v-1.5c0-.621-.504-1.125-1.125-1.125H3.375c-.621 0-1.125.504-1.125 1.125v1.5c0 .621.504 1.125 1.125 1.125z"]
    outline_archive_box = ["M20.25 7.5l-.625 10.632a2.25 2.25 0 01-2.247 2.118H6.622a2.25 2.25 0 01-2.247-2.118L3.75 7.5M10 11.25h4M3.375 7.5h17.25c.621 0 1.125-.504 1.125-1.125v-1.5c0-.621-.504-1.125-1.125-1.125H3.375c-.621 0-1.125.504-1.125 1.125v1.5c0 .621.504 1.125 1.125 1.125z"]
    outline_arrow_down_circle = ["M9 12.75l3 3m0 0l3-3m-3 3v-7.5M21 12a9 9 0 11-18 0 9 9 0 0118 0z"]
    outline_arrow_down_left = ["M19.5 4.5l-15 15m0 0h11.25m-11.25 0V8.25"]
    outline_arrow_down_on_square_stack = ["M7.5 7.5h-.75A2.25 2.25 0 004.5 9.75v7.5a2.25 2.25 0 002.25 2.25h7.5a2.25 2.25 0 002.25-2.25v-7.5a2.25 2.25 0 00-2.25-2.25h-.75m-6 3.75l3 3m0 0l3-3m-3 3V1.5m6 9h.75a2.25 2.25 0 012.25 2.25v7.5a2.25 2.25 0 01-2.25 2.25h-7.5a2.25 2.25 0 01-2.25-2.25v-.75"]
    outline_arrow_down_on_square = ["M9 8.25H7.5a2.25 2.25 0 00-2.25 2.25v9a2.25 2.25 0 002.25 2.25h9a2.25 2.25 0 002.25-2.25v-9a2.25 2.25 0 00-2.25-2.25H15M9 12l3 3m0 0l3-3m-3 3V2.25"]
    outline_arrow_down_right = ["M4.5 4.5l15 15m0 0V8.25m0 11.25H8.25"]
    outline_arrow_down_tray = ["M3 16.5v2.25A2.25 2.25 0 005.25 21h13.5A2.25 2.25 0 0021 18.75V16.5M16.5 12L12 16.5m0 0L7.5 12m4.5 4.5V3"]
    outline_arrow_down = ["M19.5 13.5L12 21m0 0l-7.5-7.5M12 21V3"]

[dalito]

I also think that pip is currently the best way.

Prefix alternatives: djanco or djc? There is currently no package on PyPi starting with djc- but several starting with dc-.

[JuroOravec]

I like djc-!

[JuroOravec]

Just a note - I tried to make a package with the icon component, but there is a bug that's blocking me. Currently we try to resolve the paths to HTML / JS / CSS at component class creation. But this causes this logic to run before Django is loaded, which throws. We need to do it lazily.