doggo

# Doggo

[![Hex](https://img.shields.io/hexpm/v/doggo)](https://hex.pm/packages/doggo) ![CI](https://github.com/woylie/doggo/workflows/CI/badge.svg) [![Coverage Status](https://coveralls.io/repos/github/woylie/doggo/badge.svg)](https://coveralls.io/github/woylie/doggo)

Headless UI component collection for Phoenix, focused on semantics and
accessibility.

For a full list of available components, please refer to the
[documentation](https://hexdocs.pm/doggo/Doggo.html).

Doggo ships as two packages: a Hex package called `doggo` that defines
Phoenix LiveView components and an npm package called `@woylie/doggo` that
defines the JavaScript hooks for those components. The hooks are described
below under [Phoenix LiveView Hooks](#phoenix-liveview-hooks).

## Installation

The package can be installed by adding `doggo` to your list of dependencies in
`mix.exs`:

```elixir
def deps do
  [
    {:doggo, "~> 0.18.4"}
  ]
end
```

Enable diagnostic checks at render time in `config/dev.exs` and
`config/test.exs` :

```elixir
config :doggo, :diagnostics, true
```

These checks raise errors if components are not wired up correctly, for example
if an accessible name is not set. If disabled, the checks are not compiled.

### Compatibility

This package is tested against the Elixir and OTP versions that are still
supported upstream. Older versions down to the requirement in `mix.exs` may
still work, but they are not covered by CI and not officially supported.

## Usage

Use `Doggo.Components` in your core components module or in a separate module.
`Doggo.Components` defines macros that generate Phoenix components.

```elixir
defmodule MyAppWeb.CoreComponents do
  use Doggo.Components
  use Phoenix.Component

  build_alert()
  build_alert_dialog()

  build_button(
    modifiers: [
      size: [values: ["normal", "small"], default: "normal"]
    ]
  )
end
```

Each modifier results in an additional attribute that is translated into a
data attribute. You can use the button defined above like this:

```html
<.button size="small">Edit</.button>
```

The resulting HTML code will look similar to:

```html
<button data-size="small">Edit</button>
```

If no `type` option is set, a `string` attribute is added, but you can use any
attribute type, as long as the value can be converted to a string. Boolean
attributes result in a presence-only boolean data attribute.

```elixir
build_button(modifiers: [full_width: [type: :boolean]])
```

If the value is `true`, the attribute is added:

```html
<!-- code -->
<.button full_width>Edit</.button>

<!-- output -->
<button data-full-width>Edit</button>
```

If the attribute is omitted or the value is `false`, the attribute is omitted:

```html
<!-- code -->
<.button full_width={false}>Edit</.button>

<!-- output -->
<button>Edit</button>
```

Most of the components have a base class that matches the component name.

You can override the base class in the component options:

```elixir
defmodule MyAppWeb.CoreComponents do
  use Doggo.Com