# `Bylaw.HTML`
[🔗](https://github.com/ryanzidago/bylaw/blob/v0.1.0-alpha.2/lib/bylaw/html.ex#L1)

Validates rendered HTML strings with explicit checks.

`validate_html/2` parses the rendered HTML once, runs the checks you choose,
and returns `:ok` or `{:error, issues}`. Bylaw does not read application
config or choose default checks for the caller.

## Usage

Choose the checks you want to enforce and pass them with the rendered HTML
string:

    html = render(view)

    checks = [
      Bylaw.HTML.Check.RequireLinkHref,
      Bylaw.HTML.Check.PreferButtonForAction,
      Bylaw.HTML.Check.PreferLinkForNavigation,
      Bylaw.HTML.Check.RequireImageAlt,
      Bylaw.HTML.Check.RequireButtonType,
      Bylaw.HTML.Check.RequireInputAutocomplete,
      Bylaw.HTML.Check.NoInlineStyle
    ]

    assert :ok = Bylaw.HTML.validate_html(html, checks)

When validation fails, `validate_html/2` returns every issue found by the
enabled checks:

    case Bylaw.HTML.validate_html(html, checks) do
      :ok -> :ok
      {:error, issues} -> flunk(inspect(issues, pretty: true))
    end

## Built-in checks

Built-in checks live under `Bylaw.HTML.Check.*`. Each check module documents
its own examples, notes, options, and copyable check specs.

## Notes

The validation boundary is the rendered HTML string. Checks can see the
browser-facing markup, but they do not know which source component or template
produced it.

## Examples

    iex> Bylaw.HTML.validate_html(~s(<a href="/settings">Settings</a>), [])
    :ok

    iex> {:error, [issue]} =
    ...>   Bylaw.HTML.validate_html(
    ...>     ~s(<button phx-click='[["navigate",{"href":"/settings","replace":false}]]'>Settings</button>),
    ...>     [Bylaw.HTML.Check.PreferLinkForNavigation]
    ...>   )
    iex> issue.check
    Bylaw.HTML.Check.PreferLinkForNavigation

# `check`

```elixir
@type check() :: module()
```

# `checks`

```elixir
@type checks() :: [check()]
```

# `validate_html`

```elixir
@spec validate_html(String.t(), checks()) ::
  :ok | {:error, [Bylaw.HTML.Issue.t(), ...]}
```

Validates rendered `html` with the explicit `checks` list.

Returns `:ok` when every check passes. Returns `{:error, issues}` when one or
more issues are found. Validation failures do not raise.

`checks` must be an explicit list of modules implementing
`Bylaw.HTML.Check`. Bylaw does not choose default HTML checks or read them
from application config.

---

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