# `PhiaUi.Editor.CitationHelpers`
[🔗](https://github.com/charlenopires/PhiaUI/blob/v0.1.17/lib/phia_ui/editor/citation_helpers.ex#L1)

Pure Elixir utilities for formatting citations and parsing BibTeX.

Provides server-side citation formatting in six academic styles (APA, MLA,
Chicago, Harvard, IEEE, ABNT) and a basic BibTeX parser for importing
reference libraries.

## Entry Format

Citation entries are maps with the following keys (all optional except `:author`
and `:title`):

    %{
      author: "Smith, J.",
      title: "Example Article",
      year: "2024",
      source: "Nature",
      url: "https://doi.org/...",
      volume: "42",
      pages: "1-20"
    }

## Usage

    alias PhiaUi.Editor.CitationHelpers

    # Format a single citation
    CitationHelpers.format_citation(entry, :apa)
    #=> "Smith, J. (2024). Example Article. Nature."

    # Format a numbered bibliography
    CitationHelpers.format_bibliography([entry1, entry2], :mla)
    #=> [{1, "Smith, J. \"Example.\" ..."}, ...]

    # Parse BibTeX
    CitationHelpers.parse_bibtex(bibtex_string)
    #=> [%{key: "smith2024", type: "article", author: "Smith, J.", ...}]

# `format_bibliography`

```elixir
@spec format_bibliography([map()], atom()) :: [{pos_integer(), String.t()}]
```

Formats a list of citation entries into a numbered bibliography.

Returns a list of `{index, formatted_string}` tuples, numbered starting at 1.

## Examples

    iex> entries = [
    ...>   %{author: "Smith, J.", title: "First", year: "2024", source: "Nature"},
    ...>   %{author: "Doe, A.", title: "Second", year: "2023", source: "Science"}
    ...> ]
    iex> PhiaUi.Editor.CitationHelpers.format_bibliography(entries, :apa)
    [{1, "Smith, J. (2024). First. Nature."}, {2, "Doe, A. (2023). Second. Science."}]

# `format_citation`

```elixir
@spec format_citation(map(), atom()) :: String.t()
```

Formats a single citation entry in the given academic style.

## Supported Styles

- `:apa`     — Author (Year). Title. Source.
- `:mla`     — Author. "Title." Source, Year.
- `:chicago` — Author. "Title." Source (Year).
- `:harvard` — Author (Year) 'Title', Source.
- `:ieee`    — Author, "Title," Source, vol. Volume, pp. Pages, Year.
- `:abnt`    — AUTHOR. Title. Source, v. Volume, p. Pages, Year.

## Examples

    iex> entry = %{author: "Smith, J.", title: "My Article", year: "2024", source: "Nature"}
    iex> PhiaUi.Editor.CitationHelpers.format_citation(entry, :apa)
    "Smith, J. (2024). My Article. Nature."

# `parse_bibtex`

```elixir
@spec parse_bibtex(String.t()) :: [map()]
```

Parses a BibTeX string and extracts entries as a list of maps.

Handles the common `@type{key, field={value}, ...}` format. Supports
`@article`, `@book`, `@inproceedings`, `@misc`, and other standard types.

Fields are lowercased and returned as string-keyed atoms. Unknown fields
are preserved as-is.

## Examples

    iex> bibtex = ~s(@article{smith2024,
    ...>   author = {Smith, John},
    ...>   title = {A Great Paper},
    ...>   year = {2024},
    ...>   journal = {Nature}
    ...> })
    iex> [entry] = PhiaUi.Editor.CitationHelpers.parse_bibtex(bibtex)
    iex> entry.key
    "smith2024"
    iex> entry.author
    "Smith, John"

---

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