Page helpers in pure SX: 3 OCaml primitives + SX data + SX helpers
Add pretty-print, read-file, env-list-typed primitives to OCaml kernel. Convert Python reference data (attrs, headers, events, primitives) to SX data files. Implement page helpers (component-source, handler-source, read-spec-file, reference-data, etc.) as pure SX functions. The helper dispatcher in HTTP mode looks up named functions in the env and calls them directly, replacing the Python IO bridge path. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1907,33 +1907,116 @@ let http_load_files env files =
|
||||
) files;
|
||||
rebind_host_extensions env
|
||||
|
||||
(* Pretty printer — AST value → formatted SX source string *)
|
||||
let pp_atom = Sx_types.inspect
|
||||
|
||||
let rec est_width = function
|
||||
| Nil -> 3 | Bool true -> 4 | Bool false -> 5
|
||||
| Number n -> String.length (if Float.is_integer n then string_of_int (int_of_float n) else Printf.sprintf "%g" n)
|
||||
| String s -> String.length s + 2
|
||||
| Symbol s -> String.length s
|
||||
| Keyword k -> String.length k + 1
|
||||
| SxExpr s -> String.length s + 2
|
||||
| List items | ListRef { contents = items } ->
|
||||
2 + List.fold_left (fun acc x -> acc + est_width x + 1) 0 items
|
||||
| _ -> 10
|
||||
|
||||
let pretty_print_value ?(max_width=80) v =
|
||||
let buf = Buffer.create 4096 in
|
||||
let rec pp indent v =
|
||||
match v with
|
||||
| List items | ListRef { contents = items } when items <> [] ->
|
||||
if est_width v <= max_width - indent then
|
||||
Buffer.add_string buf (pp_atom v)
|
||||
else begin
|
||||
Buffer.add_char buf '(';
|
||||
let head = List.hd items in
|
||||
Buffer.add_string buf (pp_atom head);
|
||||
let child_indent = indent + 2 in
|
||||
let rest = List.tl items in
|
||||
let rec emit = function
|
||||
| [] -> ()
|
||||
| Keyword k :: v :: rest ->
|
||||
Buffer.add_char buf '\n';
|
||||
Buffer.add_string buf (String.make child_indent ' ');
|
||||
Buffer.add_char buf ':';
|
||||
Buffer.add_string buf k;
|
||||
Buffer.add_char buf ' ';
|
||||
pp child_indent v;
|
||||
emit rest
|
||||
| item :: rest ->
|
||||
Buffer.add_char buf '\n';
|
||||
Buffer.add_string buf (String.make child_indent ' ');
|
||||
pp child_indent item;
|
||||
emit rest
|
||||
in
|
||||
emit rest;
|
||||
Buffer.add_char buf ')'
|
||||
end
|
||||
| _ -> Buffer.add_string buf (pp_atom v)
|
||||
in
|
||||
pp 0 v;
|
||||
Buffer.contents buf
|
||||
|
||||
let http_setup_page_helpers env =
|
||||
(* Page helpers that Python normally provides. Minimal stubs for HTTP mode.
|
||||
These return empty/nil so pages render without hanging. *)
|
||||
let bind name fn = ignore (env_bind env name (NativeFn (name, fn))) in
|
||||
(* highlight — passthrough without syntax coloring *)
|
||||
bind "highlight" (fun args ->
|
||||
|
||||
(* Primitive 1: pretty-print — AST → formatted SX source *)
|
||||
bind "pretty-print" (fun args ->
|
||||
match args with
|
||||
| String code :: _ ->
|
||||
let escaped = escape_sx_string code in
|
||||
SxExpr (Printf.sprintf "(pre :class \"text-sm overflow-x-auto\" (code \"%s\"))" escaped)
|
||||
| _ -> Nil);
|
||||
(* Stub all Python page helpers with nil/empty returns *)
|
||||
| [v] -> String (pretty_print_value v)
|
||||
| _ -> raise (Eval_error "pretty-print: expected 1 argument"));
|
||||
|
||||
(* Primitive 2: read-file — path → string contents or nil *)
|
||||
bind "read-file" (fun args ->
|
||||
match args with
|
||||
| [String path] ->
|
||||
(try
|
||||
let ic = open_in path in
|
||||
let n = in_channel_length ic in
|
||||
let s = Bytes.create n in
|
||||
really_input ic s 0 n;
|
||||
close_in ic;
|
||||
String (Bytes.to_string s)
|
||||
with _ -> Nil)
|
||||
| _ -> raise (Eval_error "read-file: expected string path"));
|
||||
|
||||
(* Primitive 3: env-list-typed — list all bindings of a given type *)
|
||||
bind "env-list-typed" (fun args ->
|
||||
match args with
|
||||
| [String type_name] ->
|
||||
let matches = ref [] in
|
||||
Hashtbl.iter (fun id v ->
|
||||
let matches_type = match type_name, v with
|
||||
| "component", Component _ -> true
|
||||
| "island", Island _ -> true
|
||||
| "lambda", Lambda _ -> true
|
||||
| "macro", Macro _ -> true
|
||||
| "native", NativeFn _ -> true
|
||||
| _ -> false
|
||||
in
|
||||
if matches_type then
|
||||
matches := String (Sx_types.unintern id) :: !matches
|
||||
) env.bindings;
|
||||
List (List.sort compare !matches)
|
||||
| _ -> raise (Eval_error "env-list-typed: expected type name string"));
|
||||
|
||||
(* helper dispatcher — looks up named function in env, calls it directly.
|
||||
In coroutine mode this goes through the Python IO bridge.
|
||||
In HTTP mode we dispatch locally to functions defined by SX helpers. *)
|
||||
bind "helper" (fun args ->
|
||||
match args with
|
||||
| String name :: rest ->
|
||||
(try
|
||||
let fn = env_get env name in
|
||||
Sx_ref.cek_call fn (List rest)
|
||||
with Eval_error _ ->
|
||||
Printf.eprintf "[helper] not found: %s\n%!" name;
|
||||
Nil)
|
||||
| _ -> raise (Eval_error "helper: expected (helper \"name\" ...args)"));
|
||||
|
||||
(* Stub remaining demo/action helpers that need real IO *)
|
||||
let stub name = bind name (fun _args -> Nil) in
|
||||
let stub_s name = bind name (fun _args -> String "") in
|
||||
stub_s "component-source";
|
||||
stub_s "handler-source";
|
||||
stub "primitives-data";
|
||||
stub "special-forms-data";
|
||||
stub "reference-data";
|
||||
stub "attr-detail-data";
|
||||
stub "header-detail-data";
|
||||
stub "event-detail-data";
|
||||
stub_s "read-spec-file";
|
||||
stub "bootstrapper-data";
|
||||
stub "bundle-analyzer-data";
|
||||
stub "routing-analyzer-data";
|
||||
stub "data-test-data";
|
||||
stub "run-spec-tests";
|
||||
stub "run-modular-tests";
|
||||
stub "streaming-demo-data";
|
||||
@@ -1942,9 +2025,7 @@ let http_setup_page_helpers env =
|
||||
stub "action:add-demo-item";
|
||||
stub "offline-demo-data";
|
||||
stub "prove-data";
|
||||
stub "page-helpers-demo-data";
|
||||
stub "spec-explorer-data";
|
||||
stub "spec-explorer-data-by-slug"
|
||||
stub "page-helpers-demo-data"
|
||||
|
||||
let http_mode port =
|
||||
let env = make_server_env () in
|
||||
@@ -1972,6 +2053,11 @@ let http_mode port =
|
||||
let dev_path = project_dir ^ "/sx/sx" in
|
||||
if Sys.file_exists (docker_path ^ "/page-functions.sx") then docker_path
|
||||
else dev_path in
|
||||
(* Expose project paths to SX helpers *)
|
||||
ignore (env_bind env "_project-dir" (String project_dir));
|
||||
ignore (env_bind env "_spec-dir" (String spec_base));
|
||||
ignore (env_bind env "_lib-dir" (String lib_base));
|
||||
ignore (env_bind env "_web-dir" (String web_base));
|
||||
let t0 = Unix.gettimeofday () in
|
||||
(* Core spec + adapters.
|
||||
Skip: primitives.sx (declarative metadata — all prims native in OCaml),
|
||||
|
||||
114
sx/sx/data/helpers.sx
Normal file
114
sx/sx/data/helpers.sx
Normal file
@@ -0,0 +1,114 @@
|
||||
(define
|
||||
component-source
|
||||
(fn
|
||||
(name)
|
||||
(let
|
||||
((val (env-get name)))
|
||||
(if
|
||||
(or (component? val) (island? val))
|
||||
(let
|
||||
((form-name (if (island? val) "defisland" "defcomp"))
|
||||
(params (component-params val))
|
||||
(body (component-body val))
|
||||
(cname (component-name val)))
|
||||
(pretty-print
|
||||
(list
|
||||
(make-symbol form-name)
|
||||
(make-symbol (str "~" cname))
|
||||
params
|
||||
body)))
|
||||
(str ";;; Not found: " name)))))
|
||||
|
||||
(define
|
||||
handler-source
|
||||
(fn
|
||||
(name)
|
||||
(let
|
||||
((val (env-get name)))
|
||||
(if
|
||||
(not (nil? val))
|
||||
(pretty-print val)
|
||||
(str ";;; Handler not found: " name)))))
|
||||
|
||||
(define _spec-dirs (list "spec" "web" "shared/sx/ref" "lib"))
|
||||
|
||||
(define
|
||||
read-spec-file
|
||||
(fn
|
||||
(filename)
|
||||
(let
|
||||
((result nil))
|
||||
(for-each
|
||||
(fn
|
||||
(dir)
|
||||
(when
|
||||
(nil? result)
|
||||
(let
|
||||
((content (read-file (str dir "/" filename))))
|
||||
(when (not (nil? content)) (set! result content)))))
|
||||
_spec-dirs)
|
||||
(or result (str ";; spec file not found: " filename)))))
|
||||
|
||||
(define primitives-data (fn () primitives-by-category))
|
||||
|
||||
(define
|
||||
_spec-search-dirs
|
||||
(fn
|
||||
()
|
||||
(list _spec-dir _web-dir _lib-dir (str _project-dir "/shared/sx/ref"))))
|
||||
|
||||
(define
|
||||
read-spec-file
|
||||
(fn
|
||||
(filename)
|
||||
(let
|
||||
((result nil))
|
||||
(for-each
|
||||
(fn
|
||||
(dir)
|
||||
(when
|
||||
(nil? result)
|
||||
(let
|
||||
((content (read-file (str dir "/" filename))))
|
||||
(when (not (nil? content)) (set! result content)))))
|
||||
(_spec-search-dirs))
|
||||
(or result (str ";; spec file not found: " filename)))))
|
||||
|
||||
(define
|
||||
attr-detail-data
|
||||
(fn (slug) (build-attr-detail slug (get attr-details slug))))
|
||||
|
||||
(define
|
||||
header-detail-data
|
||||
(fn (slug) (build-header-detail slug (get header-details slug))))
|
||||
|
||||
(define
|
||||
event-detail-data
|
||||
(fn (slug) (build-event-detail slug (get event-details slug))))
|
||||
|
||||
(define _spec-slug-map {:primitives (list "primitives.sx" "Primitives" "Built-in pure functions") :render (list "render.sx" "Renderer" "Three rendering modes") :parser (list "parser.sx" "Parser" "Tokenization and parsing") :evaluator (list "evaluator.sx" "Evaluator" "CEK machine evaluator") :signals (list "signals.sx" "Signals" "Fine-grained reactive primitives") :types (list "types.sx" "Types" "Optional gradual type system")})
|
||||
|
||||
(define
|
||||
spec-explorer-data-by-slug
|
||||
(fn
|
||||
(slug)
|
||||
(let
|
||||
((entry (get _spec-slug-map (make-keyword slug))))
|
||||
(if
|
||||
(nil? entry)
|
||||
nil
|
||||
(let
|
||||
((filename (first entry))
|
||||
(title (nth entry 1))
|
||||
(desc (nth entry 2)))
|
||||
{:description desc :title title :filename filename :source (read-spec-file filename)})))))
|
||||
|
||||
(define spec-explorer-data (fn (filename title desc) {:description (or desc "") :title (or title filename) :filename filename :source (read-spec-file filename)}))
|
||||
|
||||
(define bootstrapper-data (fn (target) {:target (or target "js") :status "not-implemented" :components (list)}))
|
||||
|
||||
(define bundle-analyzer-data (fn () {:bundles (list) :status "not-implemented"}))
|
||||
|
||||
(define routing-analyzer-data (fn () {:routes (list) :status "not-implemented"}))
|
||||
|
||||
(define data-test-data (fn () {:status "not-implemented" :tests (list)}))
|
||||
420
sx/sx/data/reference-details.sx
Normal file
420
sx/sx/data/reference-details.sx
Normal file
@@ -0,0 +1,420 @@
|
||||
;; Detail data for reference pages
|
||||
;; Auto-generated from sx/content/pages.py
|
||||
|
||||
(define header-details
|
||||
{
|
||||
"SX-Request"
|
||||
{
|
||||
:direction "request"
|
||||
:description "Sent on every sx-initiated request. Allows the server to distinguish AJAX partial requests from full page loads, and return the appropriate response format (fragment vs full page)."
|
||||
:example ";; Server-side: check for sx request\n(if (header \"SX-Request\")\n ;; Return a fragment\n (div :class \"result\" \"Partial content\")\n ;; Return full page\n (~full-page-layout ...))"
|
||||
}
|
||||
"SX-Current-URL"
|
||||
{
|
||||
:direction "request"
|
||||
:description "Sends the browser's current URL so the server knows where the user is. Useful for server-side logic that depends on context — e.g. highlighting the current nav item, or returning context-appropriate content."
|
||||
:example ";; Server reads the current URL to decide context\n(let ((url (header \"SX-Current-URL\")))\n (nav\n (a :href \"/docs\" :class (if (starts-with? url \"/docs\") \"active\" \"\") \"Docs\")\n (a :href \"/api\" :class (if (starts-with? url \"/api\") \"active\" \"\") \"API\")))"
|
||||
}
|
||||
"SX-Target"
|
||||
{
|
||||
:direction "request"
|
||||
:description "Tells the server which element will receive the response. The server can use this to tailor the response — for example, returning different content depending on whether the target is a sidebar, modal, or main panel."
|
||||
:example ";; Server checks target to decide response format\n(let ((target (header \"SX-Target\")))\n (if (= target \"#sidebar\")\n (~compact-summary :data data)\n (~full-detail :data data)))"
|
||||
}
|
||||
"SX-Components"
|
||||
{
|
||||
:direction "request"
|
||||
:description "Comma-separated list of component names the client already has cached. The server can skip sending defcomp definitions the client already knows, reducing response size. This is the component caching protocol."
|
||||
:example ";; Client sends: SX-Components: ~card,~shared:layout/nav-link,~footer\n;; Server omits those defcomps from the response.\n;; Only new/changed components are sent.\n(response\n :components (filter-new known-components)\n :content (~page-content))"
|
||||
}
|
||||
"SX-Css"
|
||||
{
|
||||
:direction "request"
|
||||
:description "Sends the CSS classes or hash the client already has. The server uses this to send only new CSS rules the client needs, avoiding duplicate rule injection. Part of the on-demand CSS protocol."
|
||||
:example ";; Client sends hash of known CSS classes\n;; Server compares and only returns new classes\n(let ((client-css (header \"SX-Css\")))\n (set-header \"SX-Css-Add\"\n (join \",\" (diff new-classes client-css))))"
|
||||
}
|
||||
"SX-History-Restore"
|
||||
{
|
||||
:direction "request"
|
||||
:description "Set to \"true\" when the browser restores a page from history (back/forward). The server can use this to return cached content or skip side effects that should only happen on initial navigation."
|
||||
:example ";; Skip analytics on history restore\n(when (not (header \"SX-History-Restore\"))\n (track-page-view url))\n(~page-content :data data)"
|
||||
}
|
||||
"SX-Css-Hash"
|
||||
{
|
||||
:direction "both"
|
||||
:description "Request: 8-character hash of the client's known CSS class set. Response: hash of the cumulative CSS set after this response. Client stores the response hash and sends it on the next request, enabling efficient CSS delta tracking."
|
||||
:example ";; Request header: SX-Css-Hash: a1b2c3d4\n;; Server compares hash to decide if CSS diff needed\n;;\n;; Response header: SX-Css-Hash: e5f6g7h8\n;; Client stores new hash for next request"
|
||||
}
|
||||
"SX-Prompt"
|
||||
{
|
||||
:direction "request"
|
||||
:description "Contains the value entered by the user in a window.prompt() dialog, triggered by the sx-prompt attribute. Allows collecting a single text input without a form."
|
||||
:example ";; Button triggers a prompt dialog\n(button :sx-get \"/api/rename\"\n :sx-prompt \"Enter new name:\"\n \"Rename\")\n\n;; Server reads the prompted value\n(let ((name (header \"SX-Prompt\")))\n (span \"Renamed to: \" (strong name)))"
|
||||
:demo "ref-header-prompt-demo"
|
||||
}
|
||||
"SX-Css-Add"
|
||||
{
|
||||
:direction "response"
|
||||
:description "Comma-separated list of new CSS class names added by this response. The client injects the corresponding CSS rules into the document. Only classes the client doesn't already have are included."
|
||||
:example ";; Server response includes new CSS classes\n;; SX-Css-Add: bg-emerald-500,text-white,rounded-xl\n;;\n;; Client automatically injects rules for these\n;; classes from the style dictionary."
|
||||
}
|
||||
"SX-Trigger"
|
||||
{
|
||||
:direction "response"
|
||||
:description "Dispatch custom DOM event(s) on the target element after the response is received. Can be a simple event name or JSON for multiple events with detail data. Useful for coordinating UI updates across components."
|
||||
:example ";; Simple event\n;; SX-Trigger: itemAdded\n;;\n;; Multiple events with data\n;; SX-Trigger: {\"itemAdded\": {\"id\": 42}, \"showNotification\": {\"message\": \"Saved!\"}}\n;;\n;; Listen in SX:\n(div :sx-on:itemAdded \"this.querySelector('.count').textContent = event.detail.id\")"
|
||||
:demo "ref-header-trigger-demo"
|
||||
}
|
||||
"SX-Trigger-After-Swap"
|
||||
{
|
||||
:direction "response"
|
||||
:description "Like SX-Trigger, but fires after the DOM swap completes. Use this when your event handler needs to reference the new DOM content that was just swapped in."
|
||||
:example ";; Server signals that new content needs initialization\n;; SX-Trigger-After-Swap: contentReady\n;;\n;; Client initializes after swap\n(div :sx-on:contentReady \"initCharts(this)\")"
|
||||
}
|
||||
"SX-Trigger-After-Settle"
|
||||
{
|
||||
:direction "response"
|
||||
:description "Like SX-Trigger, but fires after the DOM has fully settled — scripts executed, transitions complete. The latest point to react to a response."
|
||||
:example ";; SX-Trigger-After-Settle: animationReady\n;;\n;; Trigger animations after everything has settled\n(div :sx-on:animationReady \"this.classList.add('fade-in')\")"
|
||||
}
|
||||
"SX-Retarget"
|
||||
{
|
||||
:direction "response"
|
||||
:description "Override the target element for this response. The server can redirect content to a different element than what the client specified in sx-target. Useful for error messages or redirecting content dynamically."
|
||||
:example ";; Client targets a form result area\n(form :sx-post \"/api/save\"\n :sx-target \"#result\" ...)\n\n;; Server redirects errors to a different element\n;; SX-Retarget: #error-banner\n(div :class \"error\" \"Validation failed\")"
|
||||
:demo "ref-header-retarget-demo"
|
||||
}
|
||||
"SX-Reswap"
|
||||
{
|
||||
:direction "response"
|
||||
:description "Override the swap strategy for this response. The server can change how content is inserted regardless of what the client specified in sx-swap. Useful when the server decides the swap mode based on the result."
|
||||
:example ";; Client expects innerHTML swap\n(button :sx-get \"/api/check\"\n :sx-target \"#panel\" :sx-swap \"innerHTML\" ...)\n\n;; Server overrides to append instead\n;; SX-Reswap: beforeend\n(div :class \"notification\" \"New item added\")"
|
||||
}
|
||||
"SX-Redirect"
|
||||
{
|
||||
:direction "response"
|
||||
:description "Redirect the browser to a new URL using full page navigation. Unlike sx-push-url which does client-side history, this triggers a real browser navigation — useful after form submissions like login or checkout."
|
||||
:example ";; After successful login, redirect to dashboard\n;; SX-Redirect: /dashboard\n;;\n;; Server handler:\n(when (valid-credentials? user pass)\n (set-header \"SX-Redirect\" \"/dashboard\")\n (span \"Redirecting...\"))"
|
||||
}
|
||||
"SX-Refresh"
|
||||
{
|
||||
:direction "response"
|
||||
:description "Set to \"true\" to reload the current page. A blunt tool — useful when server-side state has changed significantly and a partial update won't suffice."
|
||||
:example ";; After a major state change, force refresh\n;; SX-Refresh: true\n;;\n;; Server handler:\n(when (deploy-complete?)\n (set-header \"SX-Refresh\" \"true\")\n (span \"Deployed — refreshing...\"))"
|
||||
}
|
||||
"SX-Location"
|
||||
{
|
||||
:direction "response"
|
||||
:description "Trigger client-side navigation: fetch the given URL, swap it into #main-panel, and push to browser history. Like clicking an sx-boosted link, but triggered from the server. Can be a URL string or JSON with options."
|
||||
:example ";; Simple: navigate to a page\n;; SX-Location: /docs/introduction\n;;\n;; With options:\n;; SX-Location: {\"path\": \"/(language.(doc.intro))\", \"target\": \"#sidebar\", \"swap\": \"innerHTML\"}"
|
||||
}
|
||||
"SX-Replace-Url"
|
||||
{
|
||||
:direction "response"
|
||||
:description "Replace the current URL using history.replaceState without creating a new history entry. Useful for normalizing URLs after redirects, or updating the URL to reflect server-resolved state."
|
||||
:example ";; Normalize URL after slug resolution\n;; SX-Replace-Url: /docs/introduction\n;;\n;; Server handler:\n(let ((canonical (resolve-slug slug)))\n (set-header \"SX-Replace-Url\" canonical)\n (~doc-content :slug canonical))"
|
||||
}
|
||||
})
|
||||
|
||||
(define event-details
|
||||
{
|
||||
"sx:beforeRequest"
|
||||
{
|
||||
:description "Fired on the triggering element before an sx request is issued. Call event.preventDefault() to cancel the request entirely. Useful for validation, confirmation, or conditional request logic."
|
||||
:example ";; Cancel request if form is empty\n(form :sx-post \"/api/save\"\n :sx-target \"#result\"\n :sx-on:sx:beforeRequest \"if (!this.querySelector('input').value) event.preventDefault()\"\n (input :name \"data\" :placeholder \"Required\")\n (button :type \"submit\" \"Save\"))"
|
||||
:demo "ref-event-before-request-demo"
|
||||
}
|
||||
"sx:afterRequest"
|
||||
{
|
||||
:description "Fired on the triggering element after a successful sx response is received, before the swap happens. event.detail contains the response status. Use this for logging, analytics, or pre-swap side effects."
|
||||
:example ";; Log successful requests\n(button :sx-get \"/api/data\"\n :sx-target \"#result\"\n :sx-on:sx:afterRequest \"console.log('Response received', event.detail)\"\n \"Load data\")"
|
||||
:demo "ref-event-after-request-demo"
|
||||
}
|
||||
"sx:afterSwap"
|
||||
{
|
||||
:description "Fired on the triggering element after the response content has been swapped into the DOM. event.detail contains the target element and swap style. Use this to initialize UI on newly inserted content."
|
||||
:example ";; Run code after content is swapped in\n(button :sx-get \"/api/items\"\n :sx-target \"#item-list\"\n :sx-on:sx:afterSwap \"console.log('Swapped into', event.detail.target)\"\n \"Load items\")"
|
||||
:demo "ref-event-after-swap-demo"
|
||||
}
|
||||
"sx:responseError"
|
||||
{
|
||||
:description "Fired when the server responds with an HTTP error (4xx or 5xx). event.detail contains the status code and response text. Use this for error handling, showing notifications, or retry logic."
|
||||
:example ";; Show error notification\n(div :sx-on:sx:responseError \"alert('Error: ' + event.detail.status)\"\n (button :sx-get \"/api/risky\"\n :sx-target \"#result\"\n \"Try it\")\n (div :id \"result\"))"
|
||||
:demo "ref-event-response-error-demo"
|
||||
}
|
||||
"sx:requestError"
|
||||
{
|
||||
:description "Fired when the request fails to send — typically a network error, DNS failure, or CORS issue. Unlike sx:responseError, no HTTP response was received at all. Aborted requests (e.g. from sx-sync) do not fire this event."
|
||||
:example ";; Handle network failures\n(div :sx-on:sx:requestError \"this.querySelector('.status').textContent = 'Offline'\"\n (button :sx-get \"/api/data\"\n :sx-target \"#result\"\n \"Load\")\n (span :class \"status\")\n (div :id \"result\"))"
|
||||
:demo "ref-event-request-error-demo"
|
||||
}
|
||||
"sx:validationFailed"
|
||||
{
|
||||
:description "Fired when sx-validate is set and the form fails HTML5 validation. The request is not sent. Use this to show custom validation UI or highlight invalid fields."
|
||||
:example ";; Highlight invalid fields\n(form :sx-post \"/api/save\"\n :sx-validate \"true\"\n :sx-on:sx:validationFailed \"this.classList.add('shake')\"\n (input :type \"email\" :required \"true\" :name \"email\"\n :placeholder \"Email (required)\")\n (button :type \"submit\" \"Save\"))"
|
||||
:demo "ref-event-validation-failed-demo"
|
||||
}
|
||||
"sx:clientRoute"
|
||||
{
|
||||
:description "Fired on the swap target after successful client-side routing. No server request was made — the page was rendered entirely in the browser from component definitions the client already has. event.detail contains the pathname. Use this to update navigation state, analytics, or other side effects that should run on client-only navigation. The event bubbles, so you can listen on document.body."
|
||||
:example ";; Pages with no :data are client-routable.\n;; sx-boost containers try client routing first.\n;; On success, sx:clientRoute fires on the swap target.\n(nav :sx-boost \"#main-panel\"\n (a :href \"/(etc.(essay))\" \"Essays\")\n (a :href \"/(etc.(plan))\" \"Plans\"))\n\n;; Listen in body.js:\n;; document.body.addEventListener(\"sx:clientRoute\",\n;; function(e) { updateNav(e.detail.pathname); })"
|
||||
:demo "ref-event-client-route-demo"
|
||||
}
|
||||
"sx:sseOpen"
|
||||
{
|
||||
:description "Fired when a Server-Sent Events connection is successfully established. Use this to update connection status indicators."
|
||||
:example ";; Show connected status\n(div :sx-sse \"/api/stream\"\n :sx-on:sx:sseOpen \"this.querySelector('.status').textContent = 'Connected'\"\n (span :class \"status\" \"Connecting...\")\n (div :id \"messages\"))"
|
||||
:demo "ref-event-sse-open-demo"
|
||||
}
|
||||
"sx:sseMessage"
|
||||
{
|
||||
:description "Fired when an SSE message is received and swapped into the DOM. event.detail contains the message data. Fires for each individual message."
|
||||
:example ";; Count received messages\n(div :sx-sse \"/api/stream\"\n :sx-sse-swap \"update\"\n :sx-on:sx:sseMessage \"this.dataset.count = (parseInt(this.dataset.count||0)+1)\"\n (span :class \"count\" \"0\") \" messages received\")"
|
||||
:demo "ref-event-sse-message-demo"
|
||||
}
|
||||
"sx:sseError"
|
||||
{
|
||||
:description "Fired when an SSE connection encounters an error or is closed unexpectedly. Use this to show reconnection status or fall back to polling."
|
||||
:example ";; Show disconnected status\n(div :sx-sse \"/api/stream\"\n :sx-on:sx:sseError \"this.querySelector('.status').textContent = 'Disconnected'\"\n (span :class \"status\" \"Connecting...\")\n (div :id \"messages\"))"
|
||||
:demo "ref-event-sse-error-demo"
|
||||
}
|
||||
})
|
||||
|
||||
(define attr-details
|
||||
{
|
||||
"sx-get"
|
||||
{
|
||||
:description "Issues a GET request to the given URL when triggered. The response HTML is swapped into the target element. This is the most common sx attribute — use it for loading content, navigation, and any read operation."
|
||||
:demo "ref-get-demo"
|
||||
:example "(button :sx-get \"/(geography.(hypermedia.(reference.(api.time))))\"\n :sx-target \"#ref-get-result\"\n :sx-swap \"innerHTML\"\n \"Load server time\")"
|
||||
:handler "(defhandler ref-time (&key)\n (let ((now (format-time (now) \"%H:%M:%S\")))\n (span :class \"text-stone-800 text-sm\"\n \"Server time: \" (strong now))))"
|
||||
}
|
||||
"sx-post"
|
||||
{
|
||||
:description "Issues a POST request to the given URL. Form values from the enclosing form (or sx-include target) are sent as the request body. Use for creating resources, submitting forms, and any write operation."
|
||||
:demo "ref-post-demo"
|
||||
:example "(form :sx-post \"/(geography.(hypermedia.(reference.(api.greet))))\"\n :sx-target \"#ref-post-result\"\n :sx-swap \"innerHTML\"\n (input :type \"text\" :name \"name\"\n :placeholder \"Your name\")\n (button :type \"submit\" \"Greet\"))"
|
||||
:handler "(defhandler ref-greet (&key)\n (let ((name (or (form-data \"name\") \"stranger\")))\n (span :class \"text-stone-800 text-sm\"\n \"Hello, \" (strong name) \"!\")))"
|
||||
}
|
||||
"sx-put"
|
||||
{
|
||||
:description "Issues a PUT request to the given URL. Used for full replacement updates of a resource. Form values are sent as the request body."
|
||||
:demo "ref-put-demo"
|
||||
:example "(button :sx-put \"/(geography.(hypermedia.(reference.(api.status))))\"\n :sx-target \"#ref-put-view\"\n :sx-swap \"innerHTML\"\n :sx-vals \"{\\\"status\\\": \\\"published\\\"}\"\n \"Publish\")"
|
||||
:handler "(defhandler ref-status (&key)\n (let ((status (or (form-data \"status\") \"unknown\")))\n (span :class \"text-stone-700 text-sm\"\n \"Status: \" (strong status) \" — updated via PUT\")))"
|
||||
}
|
||||
"sx-delete"
|
||||
{
|
||||
:description "Issues a DELETE request to the given URL. Commonly paired with sx-confirm for a confirmation dialog, and sx-swap \"delete\" to remove the element from the DOM."
|
||||
:demo "ref-delete-demo"
|
||||
:example "(button :sx-delete \"/(geography.(hypermedia.(reference.(api.(item.1)))))\"\n :sx-target \"#ref-del-1\"\n :sx-swap \"delete\"\n \"Remove\")"
|
||||
:handler "(defhandler ref-delete (&key item-id)\n ;; Empty response — swap \"delete\" removes the target\n \"\")"
|
||||
}
|
||||
"sx-patch"
|
||||
{
|
||||
:description "Issues a PATCH request to the given URL. Used for partial updates — only changed fields are sent. Form values are sent as the request body."
|
||||
:demo "ref-patch-demo"
|
||||
:example "(button :sx-patch \"/(geography.(hypermedia.(reference.(api.theme))))\"\n :sx-vals \"{\\\"theme\\\": \\\"dark\\\"}\"\n :sx-target \"#ref-patch-val\"\n :sx-swap \"innerHTML\"\n \"Dark\")"
|
||||
:handler "(defhandler ref-theme (&key)\n (let ((theme (or (form-data \"theme\") \"unknown\")))\n (str theme)))"
|
||||
}
|
||||
"sx-trigger"
|
||||
{
|
||||
:description "Specifies which DOM event triggers the request. Defaults to 'click' for most elements and 'submit' for forms. Supports modifiers: once, changed, delay:<time>, from:<selector>, intersect, revealed, load, every:<time>. Multiple triggers can be comma-separated."
|
||||
:demo "ref-trigger-demo"
|
||||
:example "(input :type \"text\" :name \"q\"\n :placeholder \"Type to search...\"\n :sx-get \"/(geography.(hypermedia.(reference.(api.trigger-search))))\"\n :sx-trigger \"input changed delay:300ms\"\n :sx-target \"#ref-trigger-result\"\n :sx-swap \"innerHTML\")"
|
||||
:handler "(defhandler ref-trigger-search (&key)\n (let ((q (or (request-arg \"q\") \"\")))\n (if (empty? q)\n (span \"Start typing to trigger a search.\")\n (span \"Results for: \" (strong q)))))"
|
||||
}
|
||||
"sx-target"
|
||||
{
|
||||
:description "CSS selector identifying which element receives the response content. Defaults to the element itself. Use \"closest <selector>\" to find the nearest ancestor matching the selector."
|
||||
:demo "ref-target-demo"
|
||||
:example ";; Two buttons targeting different elements\n(button :sx-get \"/(geography.(hypermedia.(reference.(api.time))))\"\n :sx-target \"#ref-target-a\"\n :sx-swap \"innerHTML\"\n \"Update Box A\")\n\n(button :sx-get \"/(geography.(hypermedia.(reference.(api.time))))\"\n :sx-target \"#ref-target-b\"\n :sx-swap \"innerHTML\"\n \"Update Box B\")"
|
||||
}
|
||||
"sx-swap"
|
||||
{
|
||||
:description "Controls how the response is swapped into the target element. Values: innerHTML (default), outerHTML, afterend, beforeend, afterbegin, beforebegin, delete, none."
|
||||
:demo "ref-swap-demo"
|
||||
:example ";; Append to the end of a list\n(button :sx-get \"/(geography.(hypermedia.(reference.(api.swap-item))))\"\n :sx-target \"#ref-swap-list\"\n :sx-swap \"beforeend\"\n \"beforeend\")\n\n;; Prepend to the start\n(button :sx-get \"/(geography.(hypermedia.(reference.(api.swap-item))))\"\n :sx-target \"#ref-swap-list\"\n :sx-swap \"afterbegin\"\n \"afterbegin\")"
|
||||
:handler "(defhandler ref-swap-item (&key)\n (let ((now (format-time (now) \"%H:%M:%S\")))\n (div :class \"text-sm text-violet-700\"\n \"New item (\" now \")\")))"
|
||||
}
|
||||
"sx-swap-oob"
|
||||
{
|
||||
:description "Out-of-band swap — updates elements elsewhere in the DOM by ID, outside the normal target. The server includes extra elements in the response with sx-swap-oob attributes, and they are swapped into matching elements in the page."
|
||||
:demo "ref-oob-demo"
|
||||
:example "(button :sx-get \"/(geography.(hypermedia.(reference.(api.oob))))\"\n :sx-target \"#ref-oob-main\"\n :sx-swap \"innerHTML\"\n \"Update both boxes\")"
|
||||
:handler "(defhandler ref-oob (&key)\n (let ((now (format-time (now) \"%H:%M:%S\")))\n (<>\n (span \"Main updated at \" now)\n (div :id \"ref-oob-side\"\n :sx-swap-oob \"innerHTML\"\n (span \"OOB updated at \" now)))))"
|
||||
}
|
||||
"sx-select"
|
||||
{
|
||||
:description "CSS selector to pick a fragment from the response HTML. Only the matching element is swapped into the target. Useful for extracting part of a full-page response."
|
||||
:demo "ref-select-demo"
|
||||
:example "(button :sx-get \"/(geography.(hypermedia.(reference.(api.select-page))))\"\n :sx-target \"#ref-select-result\"\n :sx-select \"#the-content\"\n :sx-swap \"innerHTML\"\n \"Load (selecting #the-content)\")"
|
||||
:handler "(defhandler ref-select-page (&key)\n (let ((now (format-time (now) \"%H:%M:%S\")))\n (<>\n (div :id \"the-header\" (h3 \"Page header — not selected\"))\n (div :id \"the-content\"\n (span \"Selected fragment. Time: \" now))\n (div :id \"the-footer\" (p \"Page footer — not selected\")))))"
|
||||
}
|
||||
"sx-confirm"
|
||||
{
|
||||
:description "Shows a browser confirmation dialog before issuing the request. The request is cancelled if the user clicks Cancel. The value is the message shown in the dialog."
|
||||
:demo "ref-confirm-demo"
|
||||
:example "(button :sx-delete \"/(geography.(hypermedia.(reference.(api.(item.confirm)))))\"\n :sx-target \"#ref-confirm-item\"\n :sx-swap \"delete\"\n :sx-confirm \"Are you sure you want to delete this file?\"\n \"Delete\")"
|
||||
}
|
||||
"sx-push-url"
|
||||
{
|
||||
:description "Push the request URL into the browser location bar, enabling back/forward navigation. Set to \"true\" to push the request URL, or provide a custom URL string."
|
||||
:demo "ref-pushurl-demo"
|
||||
:example "(a :href \"/(geography.(hypermedia.(reference-detail.attributes.sx-get)))\"\n :sx-get \"/(geography.(hypermedia.(reference-detail.attributes.sx-get)))\"\n :sx-target \"#main-panel\"\n :sx-select \"#main-panel\"\n :sx-swap \"outerHTML\"\n :sx-push-url \"true\"\n \"sx-get page\")"
|
||||
}
|
||||
"sx-sync"
|
||||
{
|
||||
:description "Controls synchronization of concurrent requests from the same element. Strategies: \"drop\" (ignore new while in-flight), \"replace\" (abort in-flight, send new), \"queue\" (queue and send after current completes)."
|
||||
:demo "ref-sync-demo"
|
||||
:example "(input :type \"text\" :name \"q\"\n :placeholder \"Type quickly...\"\n :sx-get \"/(geography.(hypermedia.(reference.(api.slow-echo))))\"\n :sx-trigger \"input changed delay:100ms\"\n :sx-sync \"replace\"\n :sx-target \"#ref-sync-result\"\n :sx-swap \"innerHTML\")"
|
||||
:handler "(defhandler ref-slow-echo (&key)\n (sleep 800)\n (let ((q (or (request-arg \"q\") \"\")))\n (span \"Echo: \" (strong q))))"
|
||||
}
|
||||
"sx-encoding"
|
||||
{
|
||||
:description "Sets the encoding type for the request body. Use \"multipart/form-data\" for file uploads. Defaults to application/x-www-form-urlencoded for forms."
|
||||
:demo "ref-encoding-demo"
|
||||
:example "(form :sx-post \"/(geography.(hypermedia.(reference.(api.upload-name))))\"\n :sx-encoding \"multipart/form-data\"\n :sx-target \"#ref-encoding-result\"\n :sx-swap \"innerHTML\"\n (input :type \"file\" :name \"file\")\n (button :type \"submit\" \"Upload\"))"
|
||||
:handler "(defhandler ref-upload-name (&key)\n (let ((name (or (file-name \"file\") \"(no file)\")))\n (span \"Received: \" (strong name))))"
|
||||
}
|
||||
"sx-headers"
|
||||
{
|
||||
:description "Adds custom headers to the request as a JSON object string. Useful for passing metadata like API keys or content types."
|
||||
:demo "ref-headers-demo"
|
||||
:example "(button :sx-get \"/(geography.(hypermedia.(reference.(api.echo-headers))))\"\n :sx-headers '{\"X-Custom-Token\": \"abc123\", \"X-Request-Source\": \"demo\"}'\n :sx-target \"#ref-headers-result\"\n :sx-swap \"innerHTML\"\n \"Send with custom headers\")"
|
||||
:handler "(defhandler ref-echo-headers (&key)\n (let ((headers (request-headers :prefix \"X-\")))\n (if (empty? headers)\n (span \"No custom headers received.\")\n (ul (map (fn (h)\n (li (strong (first h)) \": \" (last h)))\n headers)))))"
|
||||
}
|
||||
"sx-include"
|
||||
{
|
||||
:description "Include values from additional elements in the request. Takes a CSS selector. The matched element's form values (inputs, selects, textareas) are added to the request."
|
||||
:demo "ref-include-demo"
|
||||
:example "(select :id \"ref-inc-cat\" :name \"category\"\n (option :value \"all\" \"All\")\n (option :value \"books\" \"Books\")\n (option :value \"tools\" \"Tools\"))\n\n(button :sx-get \"/(geography.(hypermedia.(reference.(api.echo-vals))))\"\n :sx-include \"#ref-inc-cat\"\n :sx-target \"#ref-include-result\"\n :sx-swap \"innerHTML\"\n \"Filter\")"
|
||||
:handler "(defhandler ref-echo-vals (&key)\n (let ((vals (request-args)))\n (if (empty? vals)\n (span \"No values received.\")\n (ul (map (fn (v)\n (li (strong (first v)) \": \" (last v)))\n vals)))))"
|
||||
}
|
||||
"sx-vals"
|
||||
{
|
||||
:description "Adds extra values to the request as a JSON object string. These are merged with any form values. Useful for passing additional data without hidden inputs."
|
||||
:demo "ref-vals-demo"
|
||||
:example "(button :sx-post \"/(geography.(hypermedia.(reference.(api.echo-vals))))\"\n :sx-vals '{\"source\": \"demo\", \"page\": \"3\"}'\n :sx-target \"#ref-vals-result\"\n :sx-swap \"innerHTML\"\n \"Send with extra values\")"
|
||||
}
|
||||
"sx-media"
|
||||
{
|
||||
:description "Only enables the sx attributes on this element when the given CSS media query matches. When the media query does not match, the element behaves as a normal HTML element."
|
||||
:demo "ref-media-demo"
|
||||
:example "(a :href \"/(geography.(hypermedia.(reference-detail.attributes.sx-get)))\"\n :sx-get \"/(geography.(hypermedia.(reference-detail.attributes.sx-get)))\"\n :sx-target \"#main-panel\"\n :sx-select \"#main-panel\"\n :sx-swap \"outerHTML\"\n :sx-push-url \"true\"\n :sx-media \"(min-width: 768px)\"\n \"sx navigation (desktop only)\")"
|
||||
}
|
||||
"sx-disable"
|
||||
{
|
||||
:description "Disables sx processing on this element and all its children. The element renders as normal HTML without any sx behavior. Useful for opting out of sx in specific subtrees."
|
||||
:demo "ref-disable-demo"
|
||||
:example ";; Left box: sx works normally\n;; Right box: sx-disable prevents any sx behavior\n(div :sx-disable \"true\"\n (button :sx-get \"/(geography.(hypermedia.(reference.(api.time))))\"\n :sx-target \"#ref-dis-b\"\n :sx-swap \"innerHTML\"\n \"Load\")\n ;; This button will NOT fire an sx request\n )"
|
||||
}
|
||||
"sx-on:*"
|
||||
{
|
||||
:description "Inline event handler — attaches JavaScript to a DOM event. The * is replaced by the event name (e.g. sx-on:click, sx-on:keydown). The handler code runs as inline JavaScript with 'this' bound to the element."
|
||||
:demo "ref-on-demo"
|
||||
:example "(button\n :sx-on:click \"document.getElementById('ref-on-result')\n .textContent = 'Clicked at ' + new Date()\n .toLocaleTimeString()\"\n \"Click me\")"
|
||||
}
|
||||
"sx-retry"
|
||||
{
|
||||
:description "Enables exponential backoff retry on request failure. Set to \"true\" for default retry behavior (3 attempts, 1s/2s/4s delays) or provide a custom retry count."
|
||||
:demo "ref-retry-demo"
|
||||
:example "(button :sx-get \"/(geography.(hypermedia.(reference.(api.flaky))))\"\n :sx-target \"#ref-retry-result\"\n :sx-swap \"innerHTML\"\n :sx-retry \"true\"\n \"Call flaky endpoint\")"
|
||||
:handler "(defhandler ref-flaky (&key)\n (let ((n (inc-counter \"ref-flaky\")))\n (if (!= (mod n 3) 0)\n (error 503)\n (span \"Success on attempt \" n \"!\"))))"
|
||||
}
|
||||
"data-sx"
|
||||
{
|
||||
:description "Client-side rendering — evaluates the s-expression source in this attribute and renders the result into the element. No server request is made. Useful for purely client-side UI and interactive components."
|
||||
:demo "ref-data-sx-demo"
|
||||
:example "(div :data-sx \"(div :class \\\"p-3 bg-violet-50 rounded\\\"\n (h3 :class \\\"font-semibold\\\" \\\"Client-rendered\\\")\n (p \\\"Evaluated in the browser.\\\")\")"
|
||||
}
|
||||
"data-sx-env"
|
||||
{
|
||||
:description "Provides environment variables as a JSON object for data-sx rendering. These values are available as variables in the s-expression."
|
||||
:demo "ref-data-sx-env-demo"
|
||||
:example "(div\n :data-sx \"(div (h3 title) (p message))\"\n :data-sx-env '{\"title\": \"Dynamic\", \"message\": \"From env\"}')"
|
||||
}
|
||||
"sx-boost"
|
||||
{
|
||||
:description "Progressively enhance all descendant links and forms with AJAX navigation. Links become sx-get requests with pushState, forms become sx-post/sx-get requests. No explicit sx-* attributes needed on each link or form — just place sx-boost on a container. The attribute value can be a CSS selector (e.g. sx-boost=\"#main-panel\") to set the default swap target for all boosted descendants. If set to \"true\", each link/form must specify its own sx-target. Pure pages (no server data dependencies) are rendered client-side without a server request."
|
||||
:demo "ref-boost-demo"
|
||||
:example ";; Boost with configurable target\n(nav :sx-boost \"#main-panel\"\n (a :href \"/(language.(doc.introduction))\" \"Introduction\")\n (a :href \"/(language.(doc.components))\" \"Components\")\n (a :href \"/(language.(doc.evaluator))\" \"Evaluator\"))\n\n;; All links swap into #main-panel automatically.\n;; Pure pages render client-side (no server request)."
|
||||
}
|
||||
"sx-preload"
|
||||
{
|
||||
:description "Preload the response in the background when the user hovers over or focuses an element with sx-get. When they click, the cached response is used instantly instead of making a new request. Cache entries expire after 30 seconds. Values: \"mousedown\" (default, preloads on mousedown) or \"mouseover\" (preloads earlier on hover with 100ms debounce)."
|
||||
:demo "ref-preload-demo"
|
||||
:example "(button :sx-get \"/(geography.(hypermedia.(reference.(api.time))))\"\n :sx-target \"#ref-preload-result\"\n :sx-swap \"innerHTML\"\n :sx-preload \"mouseover\"\n \"Hover then click (preloaded)\")"
|
||||
:handler "(defhandler ref-preload-time (&key)\n (let ((now (format-time (now) \"%H:%M:%S.%f\")))\n (span :class \"text-stone-800 text-sm\"\n \"Preloaded at: \" (strong now))))"
|
||||
}
|
||||
"sx-preserve"
|
||||
{
|
||||
:description "Preserve an element across morph/swap operations. The element must have an id. During morphing, the element is kept in place with its full DOM state intact — event listeners, scroll position, video playback, user input, and any other state are preserved. The incoming version of the element is discarded."
|
||||
:demo "ref-preserve-demo"
|
||||
:example "(div :id \"my-player\" :sx-preserve \"true\"\n (video :src \"/media/clip.mp4\" :controls \"true\"\n \"Video playback is preserved across swaps.\"))"
|
||||
}
|
||||
"sx-indicator"
|
||||
{
|
||||
:description "Specifies a CSS selector for a loading indicator element. The indicator receives the .sx-request class during the request, and the class is removed when the request completes (success or error). Use CSS to show/hide the indicator based on the .sx-request class."
|
||||
:demo "ref-indicator-demo"
|
||||
:example "(button :sx-get \"/(geography.(hypermedia.(reference.(api.slow-echo))))\"\n :sx-target \"#ref-indicator-result\"\n :sx-swap \"innerHTML\"\n :sx-indicator \"#ref-spinner\"\n \"Load (slow)\")\n\n(span :id \"ref-spinner\"\n :class \"hidden sx-request:inline text-violet-600 text-sm\"\n \"Loading...\")"
|
||||
:handler "(defhandler ref-indicator-slow (&key)\n (sleep 1500)\n (let ((now (format-time (now) \"%H:%M:%S\")))\n (span \"Loaded at \" (strong now))))"
|
||||
}
|
||||
"sx-validate"
|
||||
{
|
||||
:description "Run browser constraint validation before sending the request. If validation fails, the request is not sent and an sx:validationFailed event is dispatched. Works with standard HTML5 validation attributes (required, pattern, minlength, etc). Set to \"true\" for built-in validation, or provide a function name for custom validation."
|
||||
:demo "ref-validate-demo"
|
||||
:example "(form :sx-post \"/(geography.(hypermedia.(reference.(api.greet))))\"\n :sx-target \"#ref-validate-result\"\n :sx-swap \"innerHTML\"\n :sx-validate \"true\"\n (input :type \"email\" :name \"email\"\n :required \"true\"\n :placeholder \"Enter email (required)\")\n (button :type \"submit\" \"Submit\"))"
|
||||
:handler "(defhandler ref-validate-greet (&key)\n (let ((email (or (form-data \"email\") \"none\")))\n (span \"Validated: \" (strong email))))"
|
||||
}
|
||||
"sx-ignore"
|
||||
{
|
||||
:description "During morph/swap, this element and its subtree are completely skipped — no attribute updates, no child reconciliation, no removal. Unlike sx-preserve (which requires an id and preserves by identity), sx-ignore works positionally and means 'don\\'t touch this subtree at all.'"
|
||||
:demo "ref-ignore-demo"
|
||||
:example "(div :sx-ignore \"true\"\n (p \"This content is never updated by morph/swap.\")\n (input :type \"text\" :placeholder \"Type here — preserved\"))"
|
||||
}
|
||||
"sx-optimistic"
|
||||
{
|
||||
:description "Apply a client-side preview of the expected result immediately, then reconcile when the server responds. On error, the original state is restored. Values: \"remove\" (hide the target), \"add-class:<name>\" (add a CSS class), \"disable\" (disable the element)."
|
||||
:demo "ref-optimistic-demo"
|
||||
:example "(button :sx-delete \"/(geography.(hypermedia.(reference.(api.(item.opt1)))))\"\n :sx-target \"#ref-opt-item\"\n :sx-swap \"delete\"\n :sx-optimistic \"remove\"\n \"Delete (optimistic)\")"
|
||||
:handler "(defhandler ref-optimistic-delete (&key)\n (sleep 800)\n \"\")"
|
||||
}
|
||||
"sx-replace-url"
|
||||
{
|
||||
:description "Replace the current URL in the browser location bar using replaceState instead of pushState. The URL changes but no new history entry is created, so the back button still goes to the previous page."
|
||||
:demo "ref-replace-url-demo"
|
||||
:example "(button :sx-get \"/(geography.(hypermedia.(reference.(api.time))))\"\n :sx-target \"#ref-replurl-result\"\n :sx-swap \"innerHTML\"\n :sx-replace-url \"true\"\n \"Load (replaces URL)\")"
|
||||
}
|
||||
"sx-disabled-elt"
|
||||
{
|
||||
:description "CSS selector for elements to disable during the request. The matched elements have their disabled property set to true when the request starts, and restored to false when the request completes (success or error). Useful for preventing double-submits on forms."
|
||||
:demo "ref-disabled-elt-demo"
|
||||
:example "(button :sx-get \"/(geography.(hypermedia.(reference.(api.slow-echo))))\"\n :sx-target \"#ref-diselt-result\"\n :sx-swap \"innerHTML\"\n :sx-disabled-elt \"this\"\n :sx-vals \"{\\\"q\\\": \\\"hello\\\"}\"\n \"Click (disables during request)\")"
|
||||
}
|
||||
"sx-prompt"
|
||||
{
|
||||
:description "Show a window.prompt dialog before the request. If the user cancels, the request is not sent. The entered value is sent as the SX-Prompt request header."
|
||||
:demo "ref-prompt-demo"
|
||||
:example "(button :sx-get \"/(geography.(hypermedia.(reference.(api.prompt-echo))))\"\n :sx-target \"#ref-prompt-result\"\n :sx-swap \"innerHTML\"\n :sx-prompt \"Enter your name:\"\n \"Prompt & send\")"
|
||||
:handler "(defhandler ref-prompt-echo (&key)\n (let ((name (or (header \"SX-Prompt\") \"anonymous\")))\n (span \"Hello, \" (strong name) \"!\")))"
|
||||
}
|
||||
"sx-params"
|
||||
{
|
||||
:description "Filter which form parameters are sent with the request. Values: \"*\" (all, default), \"none\" (no params), \"not x,y\" (exclude named params), or \"x,y\" (include only named params)."
|
||||
:demo "ref-params-demo"
|
||||
:example "(form :sx-post \"/(geography.(hypermedia.(reference.(api.echo-vals))))\"\n :sx-target \"#ref-params-result\"\n :sx-swap \"innerHTML\"\n :sx-params \"name\"\n (input :type \"text\" :name \"name\" :placeholder \"Name (sent)\")\n (input :type \"text\" :name \"secret\" :placeholder \"Secret (filtered)\")\n (button :type \"submit\" \"Submit (only name)\"))"
|
||||
}
|
||||
"sx-sse"
|
||||
{
|
||||
:description "Connect to a Server-Sent Events endpoint for real-time server push. The value is the URL to connect to. Use sx-sse-swap to specify which SSE event name to listen for. Incoming data is swapped into the target using the standard sx-swap strategy. The EventSource is automatically closed when the element is removed from the DOM."
|
||||
:demo "ref-sse-demo"
|
||||
:example "(div :sx-sse \"/(geography.(hypermedia.(reference.(api.sse-time))))\"\n :sx-sse-swap \"time\"\n :sx-target \"#ref-sse-result\"\n :sx-swap \"innerHTML\"\n (div :id \"ref-sse-result\"\n \"Waiting for SSE updates...\"))"
|
||||
}
|
||||
"sx-sse-swap"
|
||||
{
|
||||
:description "Specifies the SSE event name to listen for on the parent sx-sse connection. Defaults to \"message\" if not specified. Multiple sx-sse-swap elements can listen for different event types on the same connection."
|
||||
:demo "ref-sse-demo"
|
||||
:example "(div :sx-sse \"/events/stream\"\n (div :sx-sse-swap \"notifications\"\n :sx-target \"#notif-area\" :sx-swap \"beforeend\"\n \"Listening for notifications...\")\n (div :sx-sse-swap \"status\"\n :sx-target \"#status-bar\" :sx-swap \"innerHTML\"\n \"Listening for status updates...\"))"
|
||||
}
|
||||
})
|
||||
120
sx/sx/data/reference.sx
Normal file
120
sx/sx/data/reference.sx
Normal file
@@ -0,0 +1,120 @@
|
||||
;; Reference data for sx-docs pages
|
||||
;; Auto-generated from sx/content/pages.py
|
||||
|
||||
(define request-attrs
|
||||
(list
|
||||
(list "sx-get" "Issue a GET request to the given URL" true)
|
||||
(list "sx-post" "Issue a POST request to the given URL" true)
|
||||
(list "sx-put" "Issue a PUT request to the given URL" true)
|
||||
(list "sx-delete" "Issue a DELETE request to the given URL" true)
|
||||
(list "sx-patch" "Issue a PATCH request to the given URL" true)
|
||||
))
|
||||
|
||||
(define behavior-attrs
|
||||
(list
|
||||
(list "sx-trigger" "Specifies the event that triggers the request. Modifiers: once, changed, delay:<time>, from:<selector>, intersect, revealed, load, every:<time>" true)
|
||||
(list "sx-target" "CSS selector for the target element to update" true)
|
||||
(list "sx-swap" "How to swap the response: outerHTML, innerHTML, afterend, beforeend, afterbegin, beforebegin, delete, none" true)
|
||||
(list "sx-swap-oob" "Out-of-band swap — update elements elsewhere in the DOM by ID" true)
|
||||
(list "sx-select" "CSS selector to pick a fragment from the response" true)
|
||||
(list "sx-confirm" "Shows a confirmation dialog before issuing the request" true)
|
||||
(list "sx-push-url" "Push the request URL into the browser location bar" true)
|
||||
(list "sx-sync" "Synchronization strategy for requests from this element" true)
|
||||
(list "sx-encoding" "Set the encoding for the request (e.g. multipart/form-data)" true)
|
||||
(list "sx-headers" "Add headers to the request as a JSON string" true)
|
||||
(list "sx-include" "Include additional element values in the request" true)
|
||||
(list "sx-vals" "Add values to the request as a JSON string" true)
|
||||
(list "sx-media" "Only enable this element when the media query matches" true)
|
||||
(list "sx-disable" "Disable sx processing on this element and its children" true)
|
||||
(list "sx-on:*" "Inline event handler — e.g. sx-on:click runs JavaScript on event" true)
|
||||
(list "sx-boost" "Progressively enhance all links and forms in a container with AJAX navigation. Value can be a target selector." true)
|
||||
(list "sx-preload" "Preload content on hover/focus for instant response on click" true)
|
||||
(list "sx-preserve" "Preserve element across swaps — keeps DOM state, event listeners, and scroll position" true)
|
||||
(list "sx-indicator" "CSS selector for a loading indicator element to show/hide during requests" true)
|
||||
(list "sx-validate" "Run browser constraint validation (or custom validator) before sending the request" true)
|
||||
(list "sx-ignore" "Ignore element and its subtree during morph/swap — no updates applied" true)
|
||||
(list "sx-optimistic" "Apply optimistic UI updates immediately, reconcile on server response" true)
|
||||
(list "sx-replace-url" "Replace the current URL in the browser location bar (replaceState instead of pushState)" true)
|
||||
(list "sx-disabled-elt" "CSS selector for elements to disable during the request" true)
|
||||
(list "sx-prompt" "Show a prompt dialog before the request — input is sent as SX-Prompt header" true)
|
||||
(list "sx-params" "Filter which form parameters are sent: \"*\" (all), \"none\", \"not x,y\", or \"x,y\"" true)
|
||||
(list "sx-sse" "Connect to a Server-Sent Events endpoint for real-time server push" true)
|
||||
(list "sx-sse-swap" "SSE event name to listen for and swap into the target (default: message)" true)
|
||||
))
|
||||
|
||||
(define sx-unique-attrs
|
||||
(list
|
||||
(list "sx-retry" "Exponential backoff retry on request failure" true)
|
||||
(list "data-sx" "Client-side rendering — evaluate the sx source in this attribute and render into the element" true)
|
||||
(list "data-sx-env" "Provide environment variables as JSON for data-sx rendering" true)
|
||||
))
|
||||
|
||||
(define request-headers
|
||||
(list
|
||||
(list "SX-Request" "true" "Set on every sx-initiated request")
|
||||
(list "SX-Current-URL" "URL" "The current URL of the browser")
|
||||
(list "SX-Target" "CSS selector" "The target element for the response")
|
||||
(list "SX-Components" "~comp1,~comp2,..." "Component names the client already has cached")
|
||||
(list "SX-Css" "hash or class list" "CSS classes/hash the client already has")
|
||||
(list "SX-History-Restore" "true" "Set when restoring from browser history")
|
||||
(list "SX-Css-Hash" "8-char hash" "Hash of the client's known CSS class set")
|
||||
(list "SX-Prompt" "string" "Value entered by the user in a window.prompt dialog (from sx-prompt)")
|
||||
))
|
||||
|
||||
(define response-headers
|
||||
(list
|
||||
(list "SX-Css-Hash" "8-char hash" "Hash of the cumulative CSS class set after this response")
|
||||
(list "SX-Css-Add" "class1,class2,..." "New CSS classes added by this response")
|
||||
(list "SX-Trigger" "event or JSON" "Dispatch custom event(s) on the target element after the request")
|
||||
(list "SX-Trigger-After-Swap" "event or JSON" "Dispatch custom event(s) after the swap completes")
|
||||
(list "SX-Trigger-After-Settle" "event or JSON" "Dispatch custom event(s) after the DOM settles")
|
||||
(list "SX-Retarget" "CSS selector" "Override the target element for this response")
|
||||
(list "SX-Reswap" "swap strategy" "Override the swap strategy for this response")
|
||||
(list "SX-Redirect" "URL" "Redirect the browser to a new URL (full navigation)")
|
||||
(list "SX-Refresh" "true" "Reload the current page")
|
||||
(list "SX-Location" "URL or JSON" "Client-side navigation — fetch URL, swap into #main-panel, pushState")
|
||||
(list "SX-Replace-Url" "URL" "Replace the current URL using replaceState (server-side override)")
|
||||
))
|
||||
|
||||
(define events-list
|
||||
(list
|
||||
(list "sx:beforeRequest" "Fired before an sx request is issued. Call preventDefault() to cancel.")
|
||||
(list "sx:afterRequest" "Fired after a successful sx response is received.")
|
||||
(list "sx:afterSwap" "Fired after the response has been swapped into the DOM.")
|
||||
(list "sx:responseError" "Fired on HTTP error responses (4xx, 5xx).")
|
||||
(list "sx:requestError" "Fired when the request fails to send (network error, abort).")
|
||||
(list "sx:validationFailed" "Fired when sx-validate blocks a request due to invalid form data.")
|
||||
(list "sx:clientRoute" "Fired after successful client-side routing (no server request).")
|
||||
(list "sx:sseOpen" "Fired when an SSE connection is established.")
|
||||
(list "sx:sseMessage" "Fired when an SSE message is received and swapped.")
|
||||
(list "sx:sseError" "Fired when an SSE connection encounters an error.")
|
||||
))
|
||||
|
||||
(define js-api-list
|
||||
(list
|
||||
(list "Sx.parse(text)" "Parse a single s-expression from text")
|
||||
(list "Sx.parseAll(text)" "Parse multiple s-expressions from text")
|
||||
(list "Sx.eval(expr, env)" "Evaluate an expression in the given environment")
|
||||
(list "Sx.render(expr, env)" "Render an expression to DOM nodes")
|
||||
(list "Sx.renderToString(expr, env)" "Render an expression to an HTML string (requires sx-test.js)")
|
||||
(list "Sx.renderComponent(name, kwargs, env)" "Render a named component with keyword arguments")
|
||||
(list "Sx.loadComponents(text)" "Parse and register component definitions")
|
||||
(list "Sx.getEnv()" "Get the current component environment")
|
||||
(list "Sx.mount(target, expr, env)" "Mount an expression into a DOM element")
|
||||
(list "Sx.update(target, newEnv)" "Re-render an element with new environment data")
|
||||
(list "Sx.hydrate(root)" "Find and render all [data-sx] elements within root")
|
||||
(list "SxEngine.process(root)" "Process all sx attributes in the DOM subtree")
|
||||
(list "SxEngine.executeRequest(elt, verb, url)" "Programmatically trigger an sx request")
|
||||
(list "SxEngine.config.globalViewTransitions" "Enable View Transitions API globally for all swaps (default: false)")
|
||||
))
|
||||
|
||||
(define primitives-by-category
|
||||
{:Arithmetic (list "+" "-" "*" "/" "mod" "sqrt" "pow" "abs" "floor" "ceil" "round" "min" "max")
|
||||
:Comparison (list "=" "!=" "<" ">" "<=" ">=")
|
||||
:Logic (list "not" "and" "or")
|
||||
:String (list "str" "upper" "lower" "trim" "split" "join" "index-of" "starts-with?" "ends-with?" "replace" "substring")
|
||||
:Collections (list "list" "dict" "len" "first" "last" "rest" "nth" "cons" "append" "keys" "vals" "merge" "assoc" "range" "concat" "reverse" "sort" "flatten" "zip")
|
||||
:Higher-Order (list "map" "map-indexed" "filter" "reduce" "some" "every?" "for-each")
|
||||
:Predicates (list "nil?" "number?" "string?" "list?" "dict?" "empty?" "contains?" "odd?" "even?" "zero?")
|
||||
:Type-Conversion (list "int" "float" "number")
|
||||
})
|
||||
Reference in New Issue
Block a user