# `GanttEx.Live.Gantt`
[🔗](https://github.com/rocket4ce/gantt_ex/blob/v0.1.0/lib/gantt_ex/live/gantt.ex#L1)

An interactive Gantt chart LiveComponent.

    <.live_component
      module={GanttEx.Live.Gantt}
      id="project-gantt"
      tasks={@tasks}
      links={@links}
      locale="es"
    />

The chart keeps its own UI state (selection, expanded branches, zoom,
dialogs) and applies every user change immediately. Changes are reported
to the parent LiveView as `{GanttEx, %GanttEx.Event{}}` messages so they
can be persisted (see `GanttEx.Event` and the "Persistence" guide).
Whenever the parent renders the component with different `tasks` or
`links`, the chart reloads them while preserving its UI state.

## Features

  * task grid with tree, configurable/sortable/resizable columns and inline editing
  * tasks, projects (dates rolled up from children) and milestones
  * drag & drop to move, resize and change progress; drag to reorder rows
  * finish-to-start, start-to-start, finish-to-finish and start-to-finish
    dependencies with lag, drawn by dragging between bar edges
  * zoomable time scale (hours to years) and customizable zoom levels
  * lightbox editor, quick info popup and tooltips
  * keyboard navigation, fullscreen, print, export (JSON, CSV, iCal, MS Project)
  * drag on the timeline to create tasks, or to pan the chart
  * 8 bundled languages, light/dark themes and WAI-ARIA roles

## Attributes

Data:

  * `:id` (required) - DOM id of the chart.
  * `:tasks` - list of tasks (maps, keyword lists or structs, see `GanttEx.Task`).
  * `:links` - list of links (see `GanttEx.Link`).
  * `:duration_unit` - unit of durations and lags. Defaults to `:day`.
  * `:work_time` - durations count only working time. Defaults to `false`.
  * `:calendar` - the global working calendar: a `GanttEx.Calendar` or its
    options (`work_days`, `hours`, `holidays`, `working_dates`).
  * `:calendars` - more calendars, referenced by the `:calendar_id` of tasks.

Behaviour:

  * `:readonly` - disables every edition. Defaults to `false`.
  * `:lightbox` - opens the task editor on double click / Enter / "+". Defaults to `true`.
  * `:lightbox_sections` - lightbox fields to show, any of `:text`, `:type`,
    `:parent`, `:time` and `:progress`. Defaults to all of them.
  * `:inline_edit` - click a cell of the selected row to edit it. Defaults to `true`.
  * `:quick_info` - show a popup when a bar is clicked. Defaults to `true`.
  * `:tooltips` - show tooltips when hovering bars. Defaults to `true`.
  * `:reorder` - drag rows in the grid to reorder or re-parent tasks. Defaults to `true`.
  * `:links_editable` - draw and edit dependencies. Defaults to `true`.
  * `:auto_scheduling` - after every change, move tasks so that dependencies
    and constraints hold (see `GanttEx.Scheduler`). The lightbox gets a
    constraint section. Defaults to `false`.
  * `:auto_scheduling_strict` - also move tasks earlier, to their earliest
    possible date. Defaults to `false`.
  * `:critical_path` - highlight the critical path (see `GanttEx.CriticalPath`).
    The toolbar has a toggle for it. Defaults to `false`.
  * `:show_slack` - draw the free slack of each task after its bar.
    Defaults to `false`.
  * `:resources` - the resources tasks are assigned to (see `GanttEx.Resource`).
    Tasks list their assignments in `:resources`; the lightbox gets a
    `:resources` section and grids can show a `:resources` column.
  * `:auto_types` - tasks with children become projects and projects
    without children become tasks. Defaults to `false`.
  * `:group_by` - group the tasks under virtual rows: a task field (`:type`),
    a `:meta` key (`:owner`), `:resources` (a task appears under each of its
    resources) or a function returning the group(s) of a task.
  * `:group_label` - a function returning the label of a group.
  * `:resource_panel` - show the load of every resource below the chart
    (see `GanttEx.ResourceLoad`). Defaults to `false`.
  * `:baselines` - draw the baseline (`:planned_start` / `:planned_end`)
    below each bar. Deadlines (`:deadline`) are always drawn, and tasks that
    end after them are marked as overdue. Defaults to `false`.
  * `:undo` - undo and redo with the toolbar or Ctrl/Cmd+Z and
    Ctrl/Cmd+Shift+Z (Ctrl+Y). Undone changes are reported as events too.
    Defaults to `true`.
  * `:drag_create` - drag on an empty area of the timeline to create a task
    (otherwise dragging pans the chart; hold Shift for the other behaviour).
    Defaults to `false`.
  * `:smart_rendering` - render only the rows around the visible area.
    `:auto` (the default) enables it above 120 visible rows; `true` or `false`
    force it.
  * `:filter` - a 1-arity function returning `true` for the tasks to show
    (their ancestors are shown too).
  * `:notify` - the pid that receives the events. Defaults to the parent LiveView.

Time scale:

  * `:zoom` - initial zoom level name. Defaults to `:day`.
  * `:zoom_levels` - custom levels (see `GanttEx.Zoom`).
  * `:start_date`, `:end_date` - fixed visible range. By default the range
    fits the tasks.
  * `:week_start` - first day of the week (`1` = Monday, `7` = Sunday). Defaults to `1`.
  * `:weekend` - ISO days highlighted as non-working. Defaults to `[6, 7]`.
  * `:today` - the current date, used by the "Today" button. Defaults to now.
  * `:markers` - vertical lines marking dates (see `GanttEx.Marker`).
  * `:today_marker` - add a marker for today. Defaults to `false`.

Appearance:

  * `:locale` - one of `GanttEx.I18n.locales/0`. Defaults to `"en"`.
  * `:theme` - `"auto"` (follows `prefers-color-scheme` or a `data-theme`
    attribute on an ancestor), `"light"` or `"dark"`. Defaults to `"auto"`.
  * `:height` - CSS height of the scrollable area. Defaults to `"640px"`.
  * `:row_height`, `:bar_height`, `:scale_height` - sizes in pixels.
  * `:grid_width` - width of the grid in pixels. Defaults to the sum of the
    column widths. `:show_grid` hides it.
  * `:toolbar` - show the built-in toolbar. Defaults to `true`.
  * `:export_formats` - formats offered by the toolbar: `:json`, `:csv`, `:ical`,
    `:ms_project`, `:svg` and `:png` (see `GanttEx.Export`).
  * `:export_filename` - base name of exported files. Defaults to `"gantt"`.
  * `:task_class` - a function returning extra CSS classes for a task bar.
  * `:class` - extra classes for the root element.

## Slots

  * `:column` - grid columns. Attributes: `field` (required: `:text`,
    `:start_date`, `:end_date`, `:duration`, `:progress`, `:type`, `:add` or
    any key of the task `:meta`), `label`, `width`, `align`, `tree`
    (shows the tree in this column), `editor` (`:text`, `:date`, `:number`,
    `:progress`, `:type` or `nil`) and `sortable`. The inner block receives
    the task:

        <:column field={:owner} label="Owner" width={120} :let={task}>
          {task.meta[:owner]}
        </:column>

  * `:task_text` - content of the bars, receives the task.
  * `:tooltip` - content of the tooltips, receives the task.
  * `:lightbox_fields` - extra lightbox fields, receives the form. Values
    are stored in the task `:meta`.
  * `:toolbar_actions` - extra content for the toolbar.

## Controlling the chart from the parent

Use `zoom/2`, `expand_all/1`, `collapse_all/1`, `select/2` and `reload/1`,
which wrap `Phoenix.LiveView.send_update/2`.

## JavaScript

Drag & drop needs the bundled hook. Add it to your `LiveSocket`:

    import {hooks as ganttHooks} from "phoenix-colocated/gantt_ex"

    const liveSocket = new LiveSocket("/live", Socket, {
      hooks: {...colocatedHooks, ...ganttHooks},
    })

and the styles to your `app.css`:

    @import "phoenix-colocated/gantt_ex/colocated.css";

# `collapse_all`

```elixir
@spec collapse_all(String.t()) :: :ok
```

Collapses every branch of the chart.

# `expand_all`

```elixir
@spec expand_all(String.t()) :: :ok
```

Expands every branch of the chart.

# `reload`

```elixir
@spec reload(String.t()) :: :ok
```

Forces the chart to reload its data from the last `tasks` and `links` it
received, discarding local changes. Useful when the parent rejected a change
and its data did not change.

# `select`

```elixir
@spec select(String.t(), GanttEx.Task.id() | nil) :: :ok
```

Selects the task with `task_id` (or clears the selection with `nil`).

# `zoom`

```elixir
@spec zoom(String.t(), atom()) :: :ok
```

Changes the zoom level of the chart with the given `id`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*