From 2d6e361d46365aa679e69321c6da177de7f32f7d Mon Sep 17 00:00:00 2001
From: Richard Ward <JohnDoe6345789@gmail.com>
Date: Tue, 30 Dec 2025 12:42:21 +0000
Subject: [PATCH] update: ui,packages,lua (6 files)

---
 packages/ui_home/seed/scripts/navigate.lua    | 45 ++-----------------
 .../ui_home/seed/scripts/navigate/init.lua    | 18 ++++++++
 .../seed/scripts/navigate/open_docs.lua       | 20 +++++++++
 .../seed/scripts/navigate/to_level2.lua       | 26 +++++++++++
 .../seed/scripts/navigate/to_level3.lua       | 26 +++++++++++
 .../ui_home/seed/scripts/navigate/types.lua   | 18 ++++++++
 6 files changed, 111 insertions(+), 42 deletions(-)
 create mode 100644 packages/ui_home/seed/scripts/navigate/init.lua
 create mode 100644 packages/ui_home/seed/scripts/navigate/open_docs.lua
 create mode 100644 packages/ui_home/seed/scripts/navigate/to_level2.lua
 create mode 100644 packages/ui_home/seed/scripts/navigate/to_level3.lua
 create mode 100644 packages/ui_home/seed/scripts/navigate/types.lua

diff --git a/packages/ui_home/seed/scripts/navigate.lua b/packages/ui_home/seed/scripts/navigate.lua
index 8da193530..1147bccf1 100644
--- a/packages/ui_home/seed/scripts/navigate.lua
+++ b/packages/ui_home/seed/scripts/navigate.lua
@@ -1,42 +1,3 @@
--- Home page navigation handlers
-
-local check = require("check")
-local LEVELS = require("levels")
-
----@class Context
----@field user? table
-
----@class NavigationResult
----@field success boolean
----@field redirect? string
----@field route? string
----@field message? string
----@field action? string
----@field url? string
-
-local M = {}
-
----@param ctx Context
----@return NavigationResult
-function M.toLevel2(ctx)
-  if not check.can_access(ctx.user, LEVELS.USER) then
-    return { success = false, redirect = "/login" }
-  end
-  return { success = true, route = "/level2" }
-end
-
----@param ctx Context
----@return NavigationResult
-function M.toLevel3(ctx)
-  if not check.can_access(ctx.user, LEVELS.ADMIN) then
-    return { success = false, message = "Admin required" }
-  end
-  return { success = true, route = "/level3" }
-end
-
----@return NavigationResult
-function M.openDocs()
-  return { success = true, action = "external", url = "/docs" }
-end
-
-return M
+-- Navigation module redirect
+-- Functions split into navigate/ directory for 1-function-per-file pattern
+return require("navigate.init")
diff --git a/packages/ui_home/seed/scripts/navigate/init.lua b/packages/ui_home/seed/scripts/navigate/init.lua
new file mode 100644
index 000000000..64869c5f4
--- /dev/null
+++ b/packages/ui_home/seed/scripts/navigate/init.lua
@@ -0,0 +1,18 @@
+-- Navigation module facade
+-- Re-exports all navigation functions for backward compatibility
+
+local to_level2 = require("navigate.to_level2")
+local to_level3 = require("navigate.to_level3")
+local open_docs = require("navigate.open_docs")
+
+---@class NavigateModule
+---@field toLevel2 fun(ctx: Context): NavigationResult
+---@field toLevel3 fun(ctx: Context): NavigationResult
+---@field openDocs fun(): NavigationResult
+local M = {}
+
+M.toLevel2 = to_level2.toLevel2
+M.toLevel3 = to_level3.toLevel3
+M.openDocs = open_docs.openDocs
+
+return M
diff --git a/packages/ui_home/seed/scripts/navigate/open_docs.lua b/packages/ui_home/seed/scripts/navigate/open_docs.lua
new file mode 100644
index 000000000..f72ccceca
--- /dev/null
+++ b/packages/ui_home/seed/scripts/navigate/open_docs.lua
@@ -0,0 +1,20 @@
+-- Open documentation link
+
+---@class NavigationResult
+---@field success boolean
+---@field action? string
+---@field url? string
+
+local M = {}
+
+---Open documentation in external window/tab
+---@return NavigationResult
+function M.openDocs()
+  return {
+    success = true,
+    action = "external",
+    url = "/docs"
+  }
+end
+
+return M
diff --git a/packages/ui_home/seed/scripts/navigate/to_level2.lua b/packages/ui_home/seed/scripts/navigate/to_level2.lua
new file mode 100644
index 000000000..175a68b25
--- /dev/null
+++ b/packages/ui_home/seed/scripts/navigate/to_level2.lua
@@ -0,0 +1,26 @@
+-- Navigate to Level 2 (User area)
+
+local check = require("check")
+local LEVELS = require("levels")
+
+---@class Context
+---@field user? table
+
+---@class NavigationResult
+---@field success boolean
+---@field redirect? string
+---@field route? string
+
+local M = {}
+
+---Navigate to Level 2 user area with permission check
+---@param ctx Context
+---@return NavigationResult
+function M.toLevel2(ctx)
+  if not check.can_access(ctx.user, LEVELS.USER) then
+    return { success = false, redirect = "/login" }
+  end
+  return { success = true, route = "/level2" }
+end
+
+return M
diff --git a/packages/ui_home/seed/scripts/navigate/to_level3.lua b/packages/ui_home/seed/scripts/navigate/to_level3.lua
new file mode 100644
index 000000000..ace8e4128
--- /dev/null
+++ b/packages/ui_home/seed/scripts/navigate/to_level3.lua
@@ -0,0 +1,26 @@
+-- Navigate to Level 3 (Admin area)
+
+local check = require("check")
+local LEVELS = require("levels")
+
+---@class Context
+---@field user? table
+
+---@class NavigationResult
+---@field success boolean
+---@field message? string
+---@field route? string
+
+local M = {}
+
+---Navigate to Level 3 admin area with permission check
+---@param ctx Context
+---@return NavigationResult
+function M.toLevel3(ctx)
+  if not check.can_access(ctx.user, LEVELS.ADMIN) then
+    return { success = false, message = "Admin required" }
+  end
+  return { success = true, route = "/level3" }
+end
+
+return M
diff --git a/packages/ui_home/seed/scripts/navigate/types.lua b/packages/ui_home/seed/scripts/navigate/types.lua
new file mode 100644
index 000000000..c467635f7
--- /dev/null
+++ b/packages/ui_home/seed/scripts/navigate/types.lua
@@ -0,0 +1,18 @@
+-- Type definitions for navigation module
+
+---@class User
+---@field id string User identifier
+---@field level? number User permission level
+
+---@class Context
+---@field user? User Current user or nil if not authenticated
+
+---@class NavigationResult
+---@field success boolean Whether navigation was allowed
+---@field redirect? string URL to redirect to if not authorized
+---@field route? string Target route on success
+---@field message? string Error message if failed
+---@field action? string Special action type
+---@field url? string External URL for special actions
+
+return {}