Documentation / Builder packages / @html

@html

@html provides compile-time HTML helpers as a builder source-backed package. The constants fold into HTML strings during compilation.

HTML helpers

@html gives you compile-time HTML helpers. The constants fold into HTML strings during compilation and produce no runtime code.

Using helpers in .mtf files

.mtf files see @html constants without an import. You can use them directly.


        -- docs/intro.mtf
        [p: A paragraph.]

        [codeblock, $code("moth"): value = 42]

Importing helpers in .moth files

.moth files need an explicit import to use @html symbols.


    import @html {table, th, td}

Available helpers

  • p, h1 through h6, small, large, div, span for structure
  • canvas for <canvas> elements with id and style slots
  • bold, italic, underline, strikethrough for formatting
  • codeblock, table, th, td for code and tables
  • img for images with src, alt and style slots
  • center, right, left, smaller, medium, larger for style inserts

Canvas

@html wraps @web/canvas drawing into a Canvas struct with methods.


    import @html {get_canvas}

    canvas ~= get_canvas("my-canvas") catch:
        assert(false, "canvas not found")
    ;

    ~canvas.set_fill_style("red")
    ~canvas.fill_rect(10.0, 10.0, 50.0, 50.0)

For the full export surface, canvas wrapper contract and deferred surfaces, see @html advanced.

@html provides compile-time HTML helpers as a builder source-backed package. It belongs to the Builder origin family with MothSource backing, so the compiler reads ordinary Moth source from packages/html/@mod.moth. See Package origins and backing for origin and backing rules.

@html ships as a skeleton. The current export surface covers common HTML tags, a few formatting helpers, table components and a thin canvas wrapper. It will grow as the language stabilises and the standard library expands.

Implicit scope for Moth template files

Exported compile-time constants from @html are visible inside .mtf files without an explicit import. This is the primary way authors use the helpers.


        -- docs/intro.mtf
        [p: A paragraph built from the @html p helper.]

        [codeblock, $code("moth"): value = 42]

A .moth file that needs specific @html symbols can import them explicitly:


    import @html {table, th, td}

Same-directory module root constants and @html constants don't shadow each other. If both surfaces expose the same visible name, compilation fails with a collision diagnostic. See Template scope for the full collision contract.

Exported constants

All helpers are compile-time #String constants that produce HTML strings. They fold at compile time and produce no runtime code.

HTML tags

| Helper | Produces | |---|---| | p | <p> paragraph | | h1 through h6 | heading levels | | small | <small> text | | large | <large> text | | img | <img> with src, alt and style slots | | div | <div> container | | span | <span> inline container | | canvas | <canvas> with id and style slots |

Formatting helpers

| Helper | Produces | |---|---| | bold | <b> bold text | | italic | <i> italic text | | underline | <u> underlined text | | strikethrough | <s> strikethrough text |

Code and tables

| Helper | Produces | |---|---| | codeblock | <pre> code block | | table | styled <table> with header and row slots | | th | <th scope="col"> header cell | | td | <td> data cell |

Utility style inserts

These constants produce CSS property values for style slots.

| Helper | CSS | |---|---| | center | text-align: center; | | right | text-align: right; | | left | text-align: left; | | smaller | font-size: smaller; | | medium | font-size: medium; | | larger | font-size: larger; |

Canvas wrapper

@html exports a Canvas struct and two functions that wrap @web/canvas into a source-owned method-style API.

| Name | Signature | |---|---| | Canvas | struct with one field context Canvas2d | | get_canvas | |id String| -> Canvas, Error! | | get_canvas_context | |id String| -> Canvas2d, Error! |

The Canvas struct provides receiver methods for drawing: set_fill_style, fill_rect, clear_rect and stroke_rect. Each takes ~Canvas (mutable receiver) and delegates to the underlying @web/canvas free functions.


    import @html {get_canvas}

    canvas ~= get_canvas("my-canvas") catch:
        assert(false, "canvas not found")
    ;

    ~canvas.set_fill_style("red")
    ~canvas.fill_rect(10.0, 10.0, 50.0, 50.0)

Both get_canvas and get_canvas_context return through Error! because the underlying @web/canvas functions can fail when the canvas element does not exist or the browser denies a 2D context.

Backend behaviour

The compile-time constants need no runtime assets. They fold into HTML strings during compilation.

The canvas wrapper functions call through to @web/canvas, which emits JavaScript runtime assets when reachable. See @web/canvas for the runtime asset contract.

Unsupported source forms

  • Direct symbol-path imports such as import @html/p face rejection. Use grouped or namespace imports.
  • @html does not expose opaque types of its own. Canvas2d comes from @web/canvas.
  • Only compile-time constants are visible inside .mtf files. Functions and types require an explicit import in .moth files.

Deferred surfaces

@html ships as a skeleton. Future expansions include richer tag coverage, form components, accessible widget helpers, layout primitives and broader style utilities. The package grows as the language stabilises and the standard library matures. See progress matrix for current status.

Related concepts