Document flow.get_context, make embedding with player optional

doc/experimental.md

@@ -98,9 +98,8 @@ local parent_form = flow.make_gui(function(player, ctx)
     return gui.VBox{
         gui.Label{label = "Hello world"},
         other_form:embed{
-            -- Passing in the player is required for now. You must use the same
-            -- player object that you get sent by flow to avoid breakages in
-            -- the future if this becomes optional.
+            -- You can optionally pass in the player object to support older
+            -- versions of flow (before 2025-06-17).
             player = player,
 
             -- A name for the embed. If this is specified, the embedded form
@@ -177,3 +176,27 @@ Notes:
    is still supported for compatibility (and there may be uses for it, such as
    sanitising field values). Be careful not to accidentally use the wrong
    callback.
+
+## Getting a reference to the current player and context
+
+If you're making a custom widget, it might be useful to get a reference to
+`ctx` and `player` so you don't have to pass them in manually.
+
+```lua
+local function HelloWorld(def)
+    local ctx, player = flow.get_context()
+    return gui.Label{
+        label = "Hello, " .. player:get_player_name() .. "!\n" ..
+            "some_value=" .. ctx.some_value,
+        style = def.style,
+    }
+end
+
+local form = flow.make_gui(function(player, ctx)
+    ctx.some_value = 123
+    return HelloWorld{style = {font_size = "*2"}}
+end)
+```
+
+`flow.get_context()` will error when called outside a build function (as you
+should not normally do this).

embed.lua

@@ -89,9 +89,8 @@ end
 local change_ctx = ...
 
 return function(self, fields)
-    local player = fields.player
     local name = fields.name
-    local parent_ctx = flow.get_context()
+    local parent_ctx, player = flow.get_context()
     if name == nil then
         -- Don't prefix anything if name is unspecified
         return self._build(player, parent_ctx)

test.lua

@@ -977,7 +977,8 @@ describe("Flow", function()
     end)
 
     describe("Flow.embed", function()
-        local embedded_form = flow.make_gui(function(_, x)
+        local embedded_form = flow.make_gui(function(p, x)
+            assert.equals("test", p:get_player_name())
             return gui.VBox{
                 gui.Label{label = "This is the embedded form!"},
                 gui.Field{name = "test2"},
@@ -998,7 +999,7 @@ describe("Flow", function()
             test_render(function(p, _)
                 return gui.HBox{
                     gui.Label{label = "asdft"},
-                    embedded_form:embed{player = p, name = "theprefix"},
+                    embedded_form:embed{name = "theprefix"},
                     gui.Label{label = "ffaksksdf"}
                 }
             end, gui.HBox{
@@ -1016,7 +1017,7 @@ describe("Flow", function()
             test_render(function(p, _)
                 return gui.HBox{
                     gui.Label{label = "asdft"},
-                    embedded_form:embed{player = p},
+                    embedded_form:embed{},
                     gui.Label{label = "ffaksksdf"}
                 }
             end, gui.HBox{