# Django HStore Project

A monorepo for the Django HStore ecosystem providing a human-friendly,
Lit-based key-value editor for PostgreSQL hstore fields in Django admin.

- **Python**: 3.10+
- **Django**: 5.0+
- **PostgreSQL**: 14+

# django-hstore-widget API

## django_hstore_widget.widgets.HStoreFormWidget

Django admin widget that renders the custom hstore editor.

Replaces the default textarea with a Lit-based key-value editor component.
Loads the widget JavaScript as an ES module via the ``Media`` inner class.

```python
from django_hstore_widget.widgets import HStoreFormWidget

widget = HStoreFormWidget()
```

### render(name, value, attrs=None, renderer=None)

Render the widget HTML for a given form field.

- ``name`` — HTML name attribute for the field
- ``value`` — Current hstore data as a key-value mapping
- ``attrs`` — Additional HTML attributes passed to the template

### Media.js

``['admin/js/django_hstore_widget/django-hstore-widget.js']``

## django_hstore_widget.forms.HStoreFormField

Form field that uses ``HStoreFormWidget``.

Extends Django's built-in ``HStoreField`` to inject the custom widget and
override ``clean()`` so incoming values are parsed through ``json.loads``.

```python
from django_hstore_widget.forms import HStoreFormField

field = HStoreFormField()
```

### clean(value)

Parse the raw form value into a Python dict using ``json.loads``.

## django_hstore_widget.checks.check_database_backend_is_postgres

System check that warns when the default DB backend is not PostgreSQL.
Runs during ``manage.py check`` and ``manage.py migrate``.

# Frontend Architecture

Architecture
============

Overview
--------

.. mermaid::

   graph LR
        A[django_hstore_field] --> B[django_hstore_widget]
        B --> C[Django runtime]
        B --> D[Lit frontend]

django-hstore-field
-------------------

Drop-in HStoreField that auto-wires the widget. No form configuration needed.

django-hstore-widget
--------------------

Lit-based frontend component with Django admin integration. Handles rendering,
validation, and media registration.

Frontend Build Pipeline
=======================

Overview
--------

The widget frontend is built with Vite and TypeScript, producing a single
IIFE bundle loaded by Django admin.

Build Steps
-----------

1. Vite bundles ``src/frontend/index.ts`` into ``dist/components/django-hstore-widget.js``
2. ``scripts/copy.ts`` copies the bundle to ``src/django_hstore_widget/static/admin/js/django_hstore_widget/``
3. Django serves the bundle via static files

Configuration
-------------

- ``vite.config.ts`` - Entry point, output, aliases, dev server
- ``tsconfig.json`` - TypeScript compiler options, path aliases

Path Aliases
------------

.. grid:: 2
   :gutter: 1

   .. grid-item::
      :columns: 12 12 6 6

      .. code-block:: text

         $lib/*

      Resolves to ``src/frontend/lib/*``

   .. grid-item::
      :columns: 12 12 6 6

      .. code-block:: text

         $store/*

      Resolves to ``src/frontend/stores/*``

   .. grid-item::
      :columns: 12 12 6 6

      .. code-block:: text

         $mappping/*

      Resolves to ``src/frontend/mappings/*``

   .. grid-item::
      :columns: 12 12 6 6

      .. code-block:: text

         $components/*

      Resolves to ``src/frontend/components/*``

Development
-----------

.. code-block:: bash

   # Start dev server
   npm run dev

   # The dev server runs on port 9100 with HMR