ItemChart
=========

Item price-line chart. Built on top of :doc:`chart` (mixed in
via Vue's mixin mechanism); inherits ``<chart>``'s
data-fetching plumbing, exporting buttons, and the
``<loading>`` overlay. Adds item-specific features on top:
SMA series, transaction markers, multi-index overlay,
percentage mode, and a fuller range selector with custom
user-defined ranges.

Modes
-----

The chart has two display modes:

* **Value** -- classic price values over time.
* **Percentage** -- price as a percentage where the base (0%)
  is the currently first visible price point.

Toggle modes with the ``percents`` prop.

SMAs and transactions
---------------------

* When ``smas`` is ``true`` the chart shows 20 / 50 / 200-day
  Simple Moving Averages as dashed reference lines (only the
  series the backend actually supplies are drawn).
* When ``transactions`` is ``true`` the chart shows
  transaction flags as bubbles on the price line. Positive
  (buy) transactions appear with a "+" sign; negative (sell)
  transactions appear with a "-" sign.

Backing endpoint
----------------

The component does a GET against ``url`` and expects the
following JSON response shape:

.. code-block:: text

   {
       "status": true,
       "data": {
           "item": [[timestamp, price], ...],
           "indexes": [[[timestamp, price], ...], ...],
           "transactions": [...],
           "ma20": [[timestamp, value], ...],
           "ma50": [...],
           "ma200": [...],
           "plotLines": [...]
       }
   }

The ``indexes``, ``transactions``, ``maNN``, and ``plotLines``
keys are only consumed when the corresponding component prop
is set. The per-app
:class:`~richy.core.views.BaseFetchItemAjaxView` subclasses
(``FetchShareAjaxView``, ``FetchEtfAjaxView``, etc.) build
this shape; ``percents``, ``indexes``, ``transactions`` and
``smas`` are forwarded to the endpoint as query parameters so
the view can include only what's needed.

Range selector
--------------

The top-left range selector ships with 10 built-in buttons
(``1w, 1m, 3m, 6m, YTD, 1y, 3y, 5y, 10y, All``); ``3m`` is
selected by default. Custom user-defined ranges can be added
via the ``ranges`` prop -- each entry becomes an extra button:

.. code-block:: javascript

    {
        title: "LT",  // Last transaction
        from: 1500933600000,
        to: 1528416000000
    }

``from`` and ``to`` are millisecond timestamps.

Plot lines
----------

Horizontal reference lines can be drawn across the chart.
Plot-line data comes from the same async response as the
price series, under the ``plotLines`` key:

.. code-block:: python

   data["plotLines"] = [
       {
           "value": 5,
           "color": "#dc0000",
           "width": 2,
           "zIndex": 4,
           "label": {"text": "my plot line"},
       }
   ]

Usage example
-------------

Mount inside a Pug template:

.. code-block:: pug

    item-chart(
        name="share-price"
        :height="500"
        symbol="{{ object.item.symbol }}"
        url="{% url 'shares:share_fetch' object.pk %}"
        :transactions="true"
        :smas="true"
    )

Component accepts following params:

* ``name`` (required) -- unique identifier used as the DOM ID
  of the chart container (inherited from :doc:`chart`).
* ``height`` (required) -- height in pixels (inherited from
  :doc:`chart`).
* ``url`` (required) -- JSON endpoint that returns the payload
  described above (inherited from :doc:`chart`).
* ``symbol`` -- Symbol of the item.
* ``indexes`` -- Array of index symbols to overlay as
  additional reference series (dashed lines). One extra
  ``yAxis`` is added per index.
* ``transactions`` -- Boolean flag; when ``true`` the chart
  also shows transaction flags (default ``false``).
* ``smas`` -- Boolean flag; when ``true`` the chart also shows
  Simple Moving Averages (20, 50, 200 days) (default
  ``false``).
* ``percents`` -- Boolean flag; when ``true`` the y-axis is in
  percents -- relative to the first visible point (default
  ``false``).
* ``hidden`` -- Boolean flag; visibility of the chart (default
  ``false``).
* ``multipleSeries`` -- Boolean flag; when ``true`` (and
  ``percents`` is also ``true``), the ``data`` array is
  treated as pre-formatted Highcharts series rather than a
  single series for ``symbol`` (default ``false``).
* ``ranges`` -- Array of objects with ``title``, ``from``,
  ``to`` properties added as extra range-selector buttons.
  ``from`` and ``to`` are millisecond timestamps.
* ``optionOverrides`` -- Object whose keys override default
  Highcharts options (shallow merge via ``Object.assign``).