@spec candidates(iodata()) :: [String.t()]

@spec candidates(Enumerable.t()) :: Enumerable.t()

Extract Tailwind candidate strings from source text.

This accepts raw HTML, templates, JavaScript/Elixir/Lua string literals, or any other source-like text. It intentionally over-collects candidate-like tokens; use validate/1 or compile/2 to let the compiler decide which tokens are real utilities.

When passed a binary or iodata, this returns a list. When passed an enumerable such as IO.stream/2 or File.stream!/3, this returns a lazy stream of unique candidate strings.

Examples

TailwindCompilerZig.candidates(~s(<div class="flex p-4"></div>))
#=> ["div", "flex", "p-4", "/div"]

File.stream!("index.html", [], :line)
|> TailwindCompilerZig.candidates()
|> Enum.to_list()

@spec compile(
  [String.t()] | Enumerable.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Compile a list of Tailwind CSS candidate strings into minified CSS.

Options

• :theme - JSON string with theme overrides (optional)
• :preflight - whether to include the base CSS reset (default: true)
• :minify - whether to minify the CSS output (default: true). When false, the output is pretty-printed with indentation.
• :custom_css - raw CSS string to append after @layer utilities (optional). Use this for custom components or user stylesheets.
• :custom_utilities - map of %{"class-name" => "css-declarations"} (optional). These get full selector escaping, variant support, and deduplication like built-in utilities. Example: %{"btn-primary" => "background:blue;color:white"}
• :plugin_css - CSS output from a Tailwind plugin (optional). The compiler parses color variable definitions (--color-*) from :root and [data-theme] blocks and registers them as theme colors so that utilities like bg-primary, text-secondary, etc. are generated. All plugin CSS (component classes, theme blocks) is included in the output.

Examples

TailwindCompilerZig.compile(["flex", "p-4", "bg-red-500"])
#=> {:ok, "@layer theme{...}@layer base{...}@layer utilities{.bg-red-500{...}.flex{...}.p-4{...}}..."}

TailwindCompilerZig.compile(["text-lg"], theme: ~s({"spacing":"0.5rem"}))
#=> {:ok, "..."}

TailwindCompilerZig.compile(["flex"], preflight: false)
#=> {:ok, "@layer utilities{.flex{display:flex}}"}

TailwindCompilerZig.compile(["flex"], custom_css: ".custom{color:red}", preflight: false)
#=> {:ok, "@layer utilities{.flex{display:flex}}.custom{color:red}"}

TailwindCompilerZig.compile(["bg-primary"], plugin_css: daisy_css, preflight: false)
#=> {:ok, "...bg-primary{background-color:var(--color-primary)}..."}

@spec compile!(
  [String.t()],
  keyword()
) :: String.t()

Same as compile/2 but raises on error.

@spec compile_source(
  iodata() | Enumerable.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Extract candidates from source text and compile them into CSS.

This is a convenience wrapper around candidates/1 and compile/2.

@spec compile_source!(
  iodata() | Enumerable.t(),
  keyword()
) :: String.t()

Same as compile_source/2 but raises on error.

@spec validate([String.t()]) :: [String.t()]

Validate a list of token strings, returning only those recognized as valid Tailwind CSS utilities.

This is a fast check — it parses each token against the utility registry without generating CSS. Used for compile-time safelist extraction from host app source files.

Examples

TailwindCompilerZig.validate(["flex", "not-a-class", "hover:bg-blue-50", "hello"])
#=> ["flex", "hover:bg-blue-50"]