From c5c2bd89f1b9f0205a643bc60215f7c81ee8f5f6 Mon Sep 17 00:00:00 2001
From: MichaelHatherly <michaelhatherly@gmail.com>
Date: Sun, 8 Dec 2024 18:39:48 +0000
Subject: [PATCH] Add `@__once__` macro

---
 docs/src/index.md                        | 38 ++++++++++++++++++++++++
 src/HypertextTemplates.jl                |  2 ++
 src/once.jl                              | 26 ++++++++++++++++
 src/render-macro.jl                      |  7 +++--
 test/references/basics/once-button-1.txt |  1 +
 test/references/basics/once-button-2.txt |  1 +
 test/references/basics/once-page.txt     |  1 +
 test/runtests.jl                         | 38 ++++++++++++++++++++++++
 8 files changed, 112 insertions(+), 2 deletions(-)
 create mode 100644 src/once.jl
 create mode 100644 test/references/basics/once-button-1.txt
 create mode 100644 test/references/basics/once-button-2.txt
 create mode 100644 test/references/basics/once-page.txt

diff --git a/docs/src/index.md b/docs/src/index.md
index 905d9ce..2578e23 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -127,6 +127,44 @@ end
 end
 ```
 
+## `@__once__`
+
+When you need to render HTML to a page only once per page, for example a JS
+dependency that only needs including once via `<script>`, you can use this
+macro to do that. It ensures that during a single `@render` call the contents
+of each `@__once__` are only evaluated once even if the rendered components are
+called more that once.
+
+Most common use cases are for including `@link`, `@style`, or `@script` tags.
+
+```julia
+@component function jquery()
+    @__once__ begin
+        @script {src = "https://code.jquery.com/jquery-3.6.0.min.js"}
+    end
+end
+@deftag macro jquery end
+
+@component function jq_button()
+    @jquery
+    @button "Click Me"
+end
+@deftag macro jq_button end
+
+@component function page()
+    @html begin
+        @head begin
+            @jquery
+        end
+        @body begin
+            @h1 "Hello, World!"
+            @jq_button
+        end
+    end
+end
+@deftag macro page end
+```
+
 ## Property Names
 
 Typically property names, which are defined between `{}`s are written as Julia
diff --git a/src/HypertextTemplates.jl b/src/HypertextTemplates.jl
index a754c5a..26f8880 100644
--- a/src/HypertextTemplates.jl
+++ b/src/HypertextTemplates.jl
@@ -10,6 +10,7 @@ import SimpleBufferStream
 # Exports:
 
 export @<
+export @__once__
 export @__slot__
 export @cm_component
 export @component
@@ -40,6 +41,7 @@ include("template-source-lookup.jl")
 include("render.jl")
 include("stream.jl")
 include("cmfile.jl")
+include("once.jl")
 
 # Initialization:
 
diff --git a/src/once.jl b/src/once.jl
new file mode 100644
index 0000000..fdcaef2
--- /dev/null
+++ b/src/once.jl
@@ -0,0 +1,26 @@
+"""
+    @__once__ expr
+
+Evaluate `expr` only once per `@render` call.
+"""
+macro __once__(expr)
+    key = QuoteNode(Symbol(string(__module__, ':', __source__)))
+    io = esc(S"io")
+    return quote
+        if $(@__MODULE__)._missing_once_key($io, $key)
+            $(esc(expr))
+            $(@__MODULE__)._add_once_key!($io, $key)
+        end
+        nothing
+    end
+end
+
+function _get_once(io::IO)
+    once_ref = get(io, :__once__, nothing)
+    isassigned(once_ref) || (once_ref[] = Set{Symbol}())
+    once = once_ref[]
+    return isnothing(once) ? error("missing `once` object.") : once
+end
+
+_missing_once_key(io::IO, key::Symbol) = !(key in _get_once(io))
+_add_once_key!(io::IO, key::Symbol) = push!(_get_once(io), key)
diff --git a/src/render-macro.jl b/src/render-macro.jl
index 44a984c..302c5df 100644
--- a/src/render-macro.jl
+++ b/src/render-macro.jl
@@ -69,16 +69,19 @@ end
 
 function _render(dst, dom_thunk::Function, source::Tuple{String,Integer})
     io = _render_dst(dst)
-    ctx = IOContext(io, :__root__ => source)
+    ctx = IOContext(io, :__root__ => source, _once_ref())
     dom_thunk(ctx, nothing)
     return _render_return(io, dst)
 end
 function _render(dst, dom_thunk::Function, source::Nothing)
     io = _render_dst(dst)
-    dom_thunk(io, nothing)
+    ctx = IOContext(io, _once_ref())
+    dom_thunk(ctx, nothing)
     return _render_return(io, dst)
 end
 
+_once_ref() = :__once__ => Ref{Set{Symbol}}()
+
 _render_dst(io::IO) = io
 _render_dst(::Type{String}) = IOBuffer()
 _render_dst(::Type{Vector{UInt8}}) = IOBuffer()
diff --git a/test/references/basics/once-button-1.txt b/test/references/basics/once-button-1.txt
new file mode 100644
index 0000000..d61efe6
--- /dev/null
+++ b/test/references/basics/once-button-1.txt
@@ -0,0 +1 @@
+<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script><button>Click Me</button>
\ No newline at end of file
diff --git a/test/references/basics/once-button-2.txt b/test/references/basics/once-button-2.txt
new file mode 100644
index 0000000..930ff86
--- /dev/null
+++ b/test/references/basics/once-button-2.txt
@@ -0,0 +1 @@
+<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script><button>Click Me</button><button>Click Me</button>
\ No newline at end of file
diff --git a/test/references/basics/once-page.txt b/test/references/basics/once-page.txt
new file mode 100644
index 0000000..3305e0b
--- /dev/null
+++ b/test/references/basics/once-page.txt
@@ -0,0 +1 @@
+<!DOCTYPE html><html><head><script src="https://code.jquery.com/jquery-3.6.0.min.js"></script></head><body><h1>Hello, World!</h1><button>Click Me</button></body></html>
\ No newline at end of file
diff --git a/test/runtests.jl b/test/runtests.jl
index fd338e0..d6aacfe 100644
--- a/test/runtests.jl
+++ b/test/runtests.jl
@@ -79,6 +79,32 @@ end
 end
 @deftag macro streaming end
 
+@component function once_jquery()
+    @__once__ begin
+        @script {src = "https://code.jquery.com/jquery-3.6.0.min.js"}
+    end
+end
+@deftag macro once_jquery end
+
+@component function once_button()
+    @once_jquery
+    @button "Click Me"
+end
+@deftag macro once_button end
+
+@component function once_page()
+    @html begin
+        @head begin
+            @once_jquery
+        end
+        @body begin
+            @h1 "Hello, World!"
+            @once_button
+        end
+    end
+end
+@deftag macro once_page end
+
 @testset "HypertestTemplates" begin
     @testset "Basics" begin
         render_test("references/basics/html-elements.txt") do io
@@ -166,6 +192,18 @@ end
                 @span {"x-show" := "open"} "Content..."
             end
         end
+        render_test("references/basics/once-button-1.txt") do io
+            @render io @once_button
+        end
+        render_test("references/basics/once-button-2.txt") do io
+            @render io begin
+                @once_button
+                @once_button
+            end
+        end
+        render_test("references/basics/once-page.txt") do io
+            @render io @once_page
+        end
     end
     @testset "Markdown" begin
         render_test("references/markdown/markdown.txt") do io