;; ---------------------------------------------------------------------------
;; Async CSS
;; ---------------------------------------------------------------------------
(defcomp ()
  (~docs/page :title "Async CSS"

    (~docs/section :title "The Pattern" :id "pattern"
      (p "A CSSX component that needs CSS it doesn't have yet can "
         (strong "fetch and cache it before rendering") ". This is just "
         (code "~shared:pages/suspense") " combined with a style component — no new infrastructure:")
      (highlight
        "(defcomp ~cssx/styled (&key css-url css-hash fallback &rest children)\n  (if (css-cached? css-hash)\n    ;; Already have it — render immediately\n    children\n    ;; Don't have it — suspense while we fetch\n    (~shared:pages/suspense :id (str \"css-\" css-hash)\n      :fallback (or fallback (span \"\"))\n      (do\n        (fetch-css css-url css-hash)\n        children))))"
        "lisp")
      (p "The consumer never knows:")
      (highlight
        "(~cssx/styled :css-url \"/css/charts.css\" :css-hash \"abc123\"\n  (~bar-chart :data metrics))"
        "lisp"))

    (~docs/section :title "Use Cases" :id "use-cases"
      (~docs/subsection :title "Federated Components"
        (p "A " (code "~cssx/btn") " from another site arrives via IPFS with a CID pointing "
           "to its CSS. The component fetches and caches it before rendering. "
           "No coordination needed between sites.")
        (highlight
          "(defcomp ~cssx/federated-widget (&key cid &rest children)\n  (let ((css-cid (str cid \"/style.css\"))\n        (cached  (css-cached? css-cid)))\n    (if cached\n      children\n      (~shared:pages/suspense :id (str \"fed-\" cid)\n        :fallback (div :class \"animate-pulse bg-stone-100 rounded h-20\")\n        (do (fetch-css (str \"https://ipfs.io/ipfs/\" css-cid) css-cid)\n            children)))))"
          "lisp"))

      (~docs/subsection :title "Heavy UI Libraries"
        (p "Code editors, chart libraries, rich text editors — their CSS only loads "
           "when the component actually appears on screen:")
        (highlight
          "(defcomp ~cssx/code-editor (&key language value on-change)\n  (~cssx/styled :css-url \"/css/codemirror.css\" :css-hash (asset-hash \"codemirror\")\n    :fallback (pre :class \"p-4 bg-stone-900 text-stone-300 rounded\" value)\n    (div :class \"cm-editor\"\n      :data-language language\n      :data-value value)))"
          "lisp"))

      (~docs/subsection :title "Lazy Themes"
        (p "Theme CSS loads on first use, then is instant on subsequent visits:")
        (highlight
          "(defcomp ~cssx/lazy-theme (&key name &rest children)\n  (let ((css-url (str \"/css/themes/\" name \".css\"))\n        (hash    (str \"theme-\" name)))\n    (~cssx/styled :css-url css-url :css-hash hash\n      :fallback children  ;; render unstyled immediately\n      children)))"
          "lisp")))

    (~docs/section :title "How It Composes" :id "composition"
      (p "Async CSS composes with everything already in SX:")
      (ul (~tw :tokens "list-disc pl-5 space-y-1 text-stone-700")
        (li (code "~shared:pages/suspense") " handles the async gap with fallback content")
        (li "localStorage handles caching across sessions")
        (li (code "<style id=\"sx-css\">") " is the injection target (same as CSS class delivery)")
        (li "Component content-hashing tracks what the client has")
        (li "No new types, no new delivery protocol, no new spec code")))))
