djact 1.0.0__py3-none-any.whl

djact/__init__.py

@@ -0,0 +1,10 @@
+"""
+djact — Inertia.js-like bridge between Django and React.
+"""
+
+default_app_config = "djact.apps.DjactConfig"
+
+from djact.render import djact_render  # noqa: E402, F401
+
+__all__ = ["djact_render"]
+__version__ = "1.0.0"

djact/apps.py

@@ -0,0 +1,10 @@
+from django.apps import AppConfig
+
+
+class DjactConfig(AppConfig):
+    name = "djact"
+    verbose_name = "Djact"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        pass  # Reserved for signal registration or startup hooks

djact/middleware.py

@@ -0,0 +1,46 @@
+from django.http import HttpResponseRedirect
+from djact.utils import is_djact_request
+
+class Djact:
+    """Helper attached to request.djact to manage shared data."""
+    def __init__(self):
+        self._shared_data = {}
+
+    def share(self, key, value):
+        """Share data with all Djact responses in this request cycle."""
+        self._shared_data[key] = value
+
+    def get_shared(self):
+        return self._shared_data
+
+class DjactMiddleware:
+    """Annotate incoming requests and provide a response-level extension hook.
+
+    Attaches ``request.is_djact`` (``bool``) and ``request.djact`` (shared data helper).
+    """
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+
+    def __call__(self, request):
+        # --- request phase ---
+        request.is_djact = is_djact_request(request)
+        request.djact = Djact()
+
+        response = self.get_response(request)
+
+        # Handle redirects for Djact requests
+        if request.is_djact and isinstance(response, HttpResponseRedirect):
+            # Tell the JS engine where we are going
+            response['X-Djact-Location'] = response['Location']
+
+        # --- response phase ---
+        return self._process_response(request, response)
+
+    # ------------------------------------------------------------------
+    # Extension hooks
+    # ------------------------------------------------------------------
+
+    def _process_response(self, request, response):
+        """Override in a subclass to add response-level Djact logic."""
+        return response

djact/py.typed

@@ -0,0 +1 @@
+# py.typed — PEP 561 marker: this package ships inline type annotations.

djact/render.py

@@ -0,0 +1,99 @@
+"""
+djact.render
+~~~~~~~~~~~~
+Core rendering helper — the primary public API of djact.
+"""
+
+import json
+
+from django.http import JsonResponse
+from django.shortcuts import render as django_render
+
+from djact.utils import is_djact_request
+
+DJACT_HEADER = "X-Djact"
+
+# Characters that must be escaped when embedding JSON in an HTML attribute.
+# json.dumps handles < > & by default; we also ensure ' is escaped so the
+# value is safe inside single-quoted attributes.
+_JSON_ESCAPE_TABLE = str.maketrans(
+    {
+        "<": r"\u003c",
+        ">": r"\u003e",
+        "&": r"\u0026",
+        "'": r"\u0027",
+    }
+)
+
+
+def _safe_json(data: dict) -> str:
+    """Serialise *data* to a JSON string that is safe to embed in HTML attributes.
+
+    Uses ``json.dumps`` with ``ensure_ascii=False`` (so unicode characters are
+    kept readable) and then escapes the five characters that are dangerous
+    inside HTML attribute values: ``< > & ' "``.  The result can be placed
+    directly in a ``data-page="..."`` or ``data-page='...'`` attribute using
+    Django's ``|safe`` template filter without risk of XSS.
+    """
+    raw = json.dumps(data, ensure_ascii=False)
+    return raw.translate(_JSON_ESCAPE_TABLE)
+
+
+def djact_render(
+    request,
+    component: str,
+    props: dict | None = None,
+    *,
+    status: int = 200,
+    extra_context: dict | None = None,
+):
+    """Render a React component via the Djact bridge.
+
+    On a full (first-visit) request returns a complete HTML page.
+    On a Djact XHR navigation request (``X-Djact`` header) returns a
+    lightweight JSON payload so the client router can swap components
+    without a full reload.
+
+    Args:
+        request:        The current Django ``HttpRequest``.
+        component:      React component identifier string (e.g. ``"Home"``, 
+                        ``"Admin/Users"``, or ``"Auth/Login"``). This string is 
+                        passed verbatim to your frontend resolver.
+        props:          JSON-serialisable dict of props.  Defaults to ``{}``.
+        status:         HTTP status code.  Defaults to ``200``.
+        extra_context:  Additional context variables merged into the template
+                        context (full-page renders only).  Use to pass a custom
+                        ``title`` or any other template variable.
+
+    Returns:
+        ``JsonResponse``      — XHR navigation (``X-Djact`` header present).
+        ``TemplateResponse``  — Full-page first load.
+    """
+    if props is None:
+        props = {}
+
+    # Merge shared data from middleware if available
+    final_props = {}
+    if hasattr(request, "djact"):
+        final_props.update(request.djact.get_shared())
+    final_props.update(props)
+
+    page_payload: dict = {
+        "component": component,
+        "props": final_props,
+        "url": request.get_full_path(),
+    }
+
+    if is_djact_request(request):
+        return JsonResponse(page_payload, status=status)
+
+    context = {"page": _safe_json(page_payload)}
+    if extra_context:
+        context.update(extra_context)
+
+    return django_render(
+        request,
+        "djact/djact.html",
+        context,
+        status=status,
+    )

djact/static/djact/app.js

@@ -0,0 +1,591 @@
+/**
+ * djact/app.js  — v1.1.0
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Djact client-side engine.
+ *
+ * Public API
+ * ──────────
+ *   createDjactApp({ resolve, onStart?, onFinish?, onError? })
+ *   djactVisit(url, options?)
+ *   Link
+ *   useDjactPage()
+ *   useDjactLoading()
+ *
+ * Peer dependencies (supplied by host project)
+ * ─────────────────────────────────────────────
+ *   react     ≥ 18
+ *   react-dom ≥ 18
+ *
+ * Component naming
+ * ────────────────
+ *   Djact does not enforce a naming convention or folder structure. 
+ *   The string you pass to `djact_render` in Django is passed verbatim 
+ *   to your `resolve` function here.
+ *
+ *   Examples:
+ *     Django: djact_render(request, "Home") 
+ *     JS: resolve("Home")
+ *
+ *     Django: djact_render(request, "Admin/Settings")
+ *     JS: resolve("Admin/Settings")
+ *
+ *   You decide how to map these strings to files in your project.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+import React, {
+  useState,
+  useEffect,
+  useRef,
+  useCallback,
+  memo,
+} from "react";
+import { createRoot } from "react-dom/client";
+
+// ─── Internal singleton state ─────────────────────────────────────────────────
+
+/** Single React root — created once, reused for every navigation. */
+let _root = null;
+
+/**
+ * Current page: { Component, componentName, props, url }
+ * `componentName` is kept so popstate can skip a redundant re-resolve.
+ */
+let _page = null;
+
+/** User-supplied resolver: (name: string) → Component | Promise<Component> */
+let _resolve = null;
+
+/** Registered page-change listeners (used by DjactApp + useDjactPage). */
+const _pageListeners = new Set();
+
+/** Registered loading-state listeners (used by useDjactLoading). */
+const _loadingListeners = new Set();
+
+/** Guard against concurrent navigations to the same URL. */
+let _inflight = null;
+
+/** Resolved-component LRU cache — avoids re-importing the same module. */
+const _componentCache = new Map();
+const _CACHE_MAX = 50;
+
+// ─── CSRF ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Read the CSRF token from <meta name="csrf-token"> (injected by djact.html)
+ * with a fallback to the `csrftoken` cookie (standard Django behaviour).
+ *
+ * @returns {string}
+ */
+function getCsrfToken() {
+  // 1. Meta tag (preferred — always present on Djact pages).
+  const meta = document.querySelector('meta[name="csrf-token"]');
+  if (meta) return meta.getAttribute("content") ?? "";
+
+  // 2. Cookie fallback (useful when the template is overridden).
+  const match = document.cookie.match(/(?:^|;\s*)csrftoken=([^;]+)/);
+  return match ? decodeURIComponent(match[1]) : "";
+}
+
+// ─── Loading state ────────────────────────────────────────────────────────────
+
+function _setLoading(value) {
+  _loadingListeners.forEach((fn) => fn(value));
+}
+
+// ─── Component resolution + cache ─────────────────────────────────────────────
+
+/**
+ * Resolve a component name → React component type.
+ *
+ * Results are cached (LRU eviction at _CACHE_MAX entries) so repeated
+ * navigations to the same page do not re-execute the dynamic import.
+ *
+ * Supports multi-app names like "library/Dashboard" or "student/Profile" —
+ * the name is passed verbatim to the host project's `resolve` function.
+ *
+ * @param {string} name
+ * @returns {Promise<React.ComponentType>}
+ */
+async function resolveComponent(name) {
+  if (!_resolve) {
+    throw new Error("[Djact] createDjactApp() has not been called yet.");
+  }
+
+  if (_componentCache.has(name)) {
+    return _componentCache.get(name);
+  }
+
+  const mod = await Promise.resolve(_resolve(name));
+
+  // Support `export default` and re-exported default patterns.
+  const Component =
+    mod && typeof mod === "object" && "default" in mod ? mod.default : mod;
+
+  if (typeof Component !== "function") {
+    throw new Error(
+      `[Djact] resolve("${name}") did not return a React component. ` +
+        `Got: ${typeof Component}`
+    );
+  }
+
+  // Cache with simple LRU eviction.
+  if (_componentCache.size >= _CACHE_MAX) {
+    _componentCache.delete(_componentCache.keys().next().value);
+  }
+  _componentCache.set(name, Component);
+
+  return Component;
+}
+
+// ─── Internal page state ──────────────────────────────────────────────────────
+
+/**
+ * Update internal page state and notify all subscribed listeners.
+ * Skips the update (no-op) if the component name, props, and URL are
+ * all identical to the current page — preventing redundant re-renders.
+ *
+ * @param {React.ComponentType} Component
+ * @param {string}              componentName  The raw name string from Django.
+ * @param {object}              props
+ * @param {string}              url
+ */
+function _setPage(Component, componentName, props, url) {
+  // Shallow-equality guard — skip if nothing actually changed.
+  if (
+    _page &&
+    _page.componentName === componentName &&
+    _page.url === url &&
+    _shallowEqual(_page.props, props)
+  ) {
+    return;
+  }
+
+  _page = { Component, componentName, props, url };
+  _pageListeners.forEach((fn) => fn(_page));
+}
+
+/** Shallow-equal two plain objects. */
+function _shallowEqual(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  const keysA = Object.keys(a);
+  if (keysA.length !== Object.keys(b).length) return false;
+  return keysA.every((k) => a[k] === b[k]);
+}
+
+// ─── Navigation ───────────────────────────────────────────────────────────────
+
+/**
+ * djactVisit(url, options?)
+ *
+ * Perform a client-side Djact navigation.
+ *
+ * @param {string}  url
+ * @param {object}  [options]
+ * @param {boolean} [options.replace=false]  Replace history entry instead of push.
+ * @param {object}  [options.data={}]        Extra props merged onto server props.
+ * @param {boolean} [options.forceReload=false]  Bypass in-flight dedup guard.
+ * @returns {Promise<void>}
+ */
+export async function djactVisit(
+  url,
+  { replace = false, data = {}, forceReload = false } = {}
+) {
+  // ── Deduplicate concurrent requests to the same URL ──────────────────────
+  if (!forceReload && _inflight === url) {
+    return;
+  }
+  _inflight = url;
+  _setLoading(true);
+
+  let payload;
+
+  try {
+    const response = await fetch(url, {
+      headers: {
+        "X-Djact": "true",
+        "X-CSRFToken": getCsrfToken(),
+        Accept: "application/json",
+      },
+      credentials: "same-origin",
+    });
+
+    // ── Graceful HTTP error handling ─────────────────────────────────────
+    if (!response.ok) {
+      const status = response.status;
+      console.error(
+        `[Djact] Navigation to "${url}" failed — HTTP ${status}.`
+      );
+
+      if (status === 404 || status >= 500) {
+        // Hard reload so Django's own error pages are shown.
+        window.location.href = url;
+        return;
+      }
+
+      // For 3xx / 4xx (e.g. 401 login redirect), follow via hard nav.
+      const location = response.headers.get("Location");
+      window.location.href = location || url;
+      return;
+    }
+
+    payload = await response.json();
+  } catch (err) {
+    // ── Network-level error (offline, CORS, timeout) ─────────────────────
+    console.error("[Djact] Network error during navigation:", err);
+    window.location.href = url;
+    return;
+  } finally {
+    _inflight = null;
+    _setLoading(false);
+  }
+
+  const { component: name, props = {}, url: resolvedUrl } = payload;
+  const mergedProps = { ...props, ...data };
+
+  let Component;
+  try {
+    Component = await resolveComponent(name);
+  } catch (err) {
+    console.error(`[Djact] Could not resolve component "${name}":`, err);
+    // Render an inline error boundary rather than going blank.
+    _setPage(_NotFound, name, { componentName: name }, resolvedUrl || url);
+    return;
+  }
+
+  const historyUrl = resolvedUrl || url;
+
+  if (replace) {
+    window.history.replaceState(
+      { djact: true, component: name, props: mergedProps },
+      "",
+      historyUrl
+    );
+  } else {
+    window.history.pushState(
+      { djact: true, component: name, props: mergedProps },
+      "",
+      historyUrl
+    );
+  }
+
+  _setPage(Component, name, mergedProps, historyUrl);
+}
+
+// ─── Built-in fallback components ─────────────────────────────────────────────
+
+/**
+ * Shown when a component name cannot be resolved.
+ * Styled minimally so it is visible but unobtrusive.
+ */
+function _NotFound({ componentName }) {
+  return React.createElement(
+    "div",
+    {
+      style: {
+        padding: "2rem",
+        fontFamily: "monospace",
+        color: "#c0392b",
+        background: "#fff5f5",
+        border: "1px solid #f5c6cb",
+        borderRadius: "4px",
+        margin: "1rem",
+      },
+    },
+    React.createElement("strong", null, "[Djact] Component not found: "),
+    componentName
+  );
+}
+
+// ─── Root React component ─────────────────────────────────────────────────────
+
+/**
+ * DjactApp — mounted once, drives all page transitions.
+ *
+ * Uses `memo` so React can bail out of reconciliation when the parent
+ * (createRoot) triggers a synthetic re-render.
+ */
+const DjactApp = memo(function DjactApp({ initialPage }) {
+  const [page, setPage] = useState(initialPage);
+  // Track previous component name to log transitions in dev.
+  const prevNameRef = useRef(initialPage?.componentName);
+
+  useEffect(() => {
+    _pageListeners.add(setPage);
+    return () => _pageListeners.delete(setPage);
+  }, []);
+
+  useEffect(() => {
+    if (
+      process.env.NODE_ENV !== "production" &&
+      page?.componentName !== prevNameRef.current
+    ) {
+      console.debug(
+        `[Djact] ${prevNameRef.current} → ${page?.componentName} (${page?.url})`
+      );
+      prevNameRef.current = page?.componentName;
+    }
+  }, [page]);
+
+  if (!page?.Component) return null;
+
+  const { Component, props } = page;
+  return React.createElement(Component, props);
+});
+
+// ─── Bootstrap ────────────────────────────────────────────────────────────────
+
+/**
+ * createDjactApp({ resolve, onStart?, onFinish?, onError? })
+ *
+ * Bootstrap the Djact client. Call exactly once at your entry point.
+ *
+ * @param {object}    options
+ * @param {Function}  options.resolve              Maps component name → component.
+ * @param {Function}  [options.onStart]            Called before every navigation.
+ * @param {Function}  [options.onFinish]           Called after every navigation.
+ * @param {Function}  [options.onError]            Called on unrecoverable errors.
+ * @returns {Promise<void>}
+ */
+export async function createDjactApp({
+  resolve,
+  onStart,
+  onFinish,
+  onError,
+} = {}) {
+  if (!resolve || typeof resolve !== "function") {
+    throw new Error("[Djact] createDjactApp() requires a `resolve` function.");
+  }
+
+  _resolve = resolve;
+
+  // Wire up optional lifecycle hooks to the loading state broadcaster.
+  if (onStart || onFinish) {
+    _loadingListeners.add((isLoading) => {
+      if (isLoading && onStart) onStart();
+      if (!isLoading && onFinish) onFinish();
+    });
+  }
+
+  // ── Read initial page data from the DOM ──────────────────────────────────
+  const container = document.getElementById("app");
+  if (!container) {
+    const msg = '[Djact] Mount point <div id="app"> not found.';
+    console.error(msg);
+    if (onError) onError(new Error(msg));
+    return;
+  }
+
+  const rawPageData = container.dataset.page;
+  if (!rawPageData) {
+    const msg = "[Djact] data-page attribute is missing or empty on #app.";
+    console.error(msg);
+    if (onError) onError(new Error(msg));
+    return;
+  }
+
+  let pageData;
+  try {
+    pageData = JSON.parse(rawPageData);
+  } catch (err) {
+    console.error("[Djact] Failed to parse data-page JSON:", err);
+    if (onError) onError(err);
+    return;
+  }
+
+  const {
+    component: name,
+    props = {},
+    url = window.location.pathname,
+  } = pageData;
+
+  // ── Resolve initial component ────────────────────────────────────────────
+  let Component;
+  try {
+    Component = await resolveComponent(name);
+  } catch (err) {
+    console.error(`[Djact] Could not resolve initial component "${name}":`, err);
+    if (onError) onError(err);
+    Component = _NotFound;
+  }
+
+  // ── Stamp initial history state ──────────────────────────────────────────
+  window.history.replaceState(
+    { djact: true, component: name, props },
+    "",
+    url
+  );
+
+  _page = { Component, componentName: name, props, url };
+
+  // ── Mount React 18 root ──────────────────────────────────────────────────
+  _root = createRoot(container);
+  _root.render(React.createElement(DjactApp, { initialPage: _page }));
+
+  // ── popstate (browser back / forward) ───────────────────────────────────
+  window.addEventListener("popstate", async (event) => {
+    const state = event.state;
+
+    if (state?.djact) {
+      // History state already carries component + props — no network round-trip.
+      let PopComponent;
+      try {
+        PopComponent = await resolveComponent(state.component);
+      } catch (err) {
+        console.error(
+          `[Djact] popstate: could not resolve "${state.component}":`,
+          err
+        );
+        PopComponent = _NotFound;
+      }
+      _setPage(
+        PopComponent,
+        state.component,
+        state.props,
+        window.location.pathname + window.location.search
+      );
+    } else {
+      // Non-Djact history entry — do a fresh XHR fetch.
+      await djactVisit(window.location.href, { replace: true });
+    }
+  });
+}
+
+// ─── Link component ───────────────────────────────────────────────────────────
+
+/**
+ * <Link> — SPA-style anchor with active-class, replace-mode, and prefetch.
+ *
+ * @param {object}         props
+ * @param {string}         props.href              Destination URL.
+ * @param {React.ReactNode} props.children         Link content.
+ * @param {string}         [props.className]       Base CSS class.
+ * @param {string}         [props.activeClassName] Class added when href matches current URL.
+ * @param {boolean}        [props.replace]         Replace history instead of push.
+ * @param {boolean}        [props.prefetch]        Prefetch on hover (resolves + caches component).
+ * @param {Function}       [props.onClick]         Extra click handler (runs before navigation).
+ * @param {object}         [props.data]            Extra props merged into server props.
+ * @param {*}              [props.*]               Forwarded to the underlying <a>.
+ *
+ * @returns {React.ReactElement}
+ */
+export function Link({
+  href,
+  children,
+  className,
+  activeClassName = "active",
+  replace = false,
+  prefetch = false,
+  onClick,
+  data = {},
+  ...rest
+}) {
+  // ── Active state ─────────────────────────────────────────────────────────
+  const [page, setPage] = useState(_page);
+
+  useEffect(() => {
+    _pageListeners.add(setPage);
+    return () => _pageListeners.delete(setPage);
+  }, []);
+
+  const isActive =
+    page?.url === href ||
+    (href !== "/" && page?.url?.startsWith(href));
+
+  const computedClass = [
+    className,
+    isActive && activeClassName ? activeClassName : "",
+  ]
+    .filter(Boolean)
+    .join(" ") || undefined;
+
+  // ── Prefetch on hover ────────────────────────────────────────────────────
+  const handleMouseEnter = useCallback(() => {
+    if (!prefetch) return;
+    // Fire-and-forget: warms up the component cache only.
+    fetch(href, {
+      headers: { "X-Djact": "true", Accept: "application/json" },
+      credentials: "same-origin",
+    })
+      .then((r) => r.json())
+      .then((payload) => resolveComponent(payload.component))
+      .catch(() => {}); // Prefetch failures are silent.
+  }, [href, prefetch]);
+
+  // ── Click handler ────────────────────────────────────────────────────────
+  const handleClick = useCallback(
+    (event) => {
+      // Let modifier-key clicks (Cmd/Ctrl/Shift/Alt) behave natively.
+      if (
+        event.metaKey ||
+        event.ctrlKey ||
+        event.shiftKey ||
+        event.altKey
+      ) {
+        return;
+      }
+
+      if (onClick) {
+        onClick(event);
+        if (event.defaultPrevented) return;
+      }
+
+      event.preventDefault();
+      djactVisit(href, { replace, data });
+    },
+    [href, replace, data, onClick]
+  );
+
+  return React.createElement(
+    "a",
+    {
+      href,
+      className: computedClass,
+      onClick: handleClick,
+      onMouseEnter: prefetch ? handleMouseEnter : undefined,
+      "aria-current": isActive ? "page" : undefined,
+      ...rest,
+    },
+    children
+  );
+}
+
+// ─── Hooks ────────────────────────────────────────────────────────────────────
+
+/**
+ * useDjactPage()
+ *
+ * Returns the current page object: { Component, componentName, props, url }
+ *
+ * @returns {{ Component: React.ComponentType, componentName: string, props: object, url: string }}
+ */
+export function useDjactPage() {
+  const [page, setPage] = useState(_page);
+
+  useEffect(() => {
+    _pageListeners.add(setPage);
+    return () => _pageListeners.delete(setPage);
+  }, []);
+
+  return page;
+}
+
+/**
+ * useDjactLoading()
+ *
+ * Returns `true` while a navigation fetch is in progress, `false` otherwise.
+ * Use to show a progress bar or spinner.
+ *
+ * @returns {boolean}
+ */
+export function useDjactLoading() {
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    _loadingListeners.add(setLoading);
+    return () => _loadingListeners.delete(setLoading);
+  }, []);
+
+  return loading;
+}

djact/templates/djact/djact.html

@@ -0,0 +1,83 @@
+<!DOCTYPE html>
+<html lang="{{ LANGUAGE_CODE|default:'en' }}">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+
+    {# ── Title — override via context variable `title` or the block ─────── #}
+    {% block title %}
+    <title>{% if title %}{{ title|escape }}{% else %}App{% endif %}</title>
+    {% endblock %}
+
+    {% load static %}
+
+    {#
+      CSRF token — read by the JS engine (getCsrfToken()) for all
+      fetch/XHR requests.  The value is rendered by Django's csrf_token
+      tag which is already HTML-safe.
+    #}
+    <meta name="csrf-token" content="{{ csrf_token }}" />
+
+    {#
+      Application meta — useful for version-checking and debugging.
+      The djact:version value can be set via the `djact_version` context
+      variable if you inject it through a context processor.
+    #}
+    {% if djact_version %}
+    <meta name="djact:version" content="{{ djact_version }}" />
+    {% endif %}
+
+    {# ── Preconnect hints — add your CDN / font origins here ───────────── #}
+    {% block preconnect %}{% endblock %}
+
+    {# ── Stylesheets / extra head content ───────────────────────────────── #}
+    {% block head %}{% endblock %}
+  </head>
+
+  <body class="{% block body_class %}{% endblock %}">
+
+    {#
+      ── Loading indicator ────────────────────────────────────────────────
+      This element is shown while the initial JS bundle is loading.
+      Djact hides it automatically once the React root is mounted.
+      Style it however you like; the id="djact-loading" is the hook.
+    #}
+    {% block loading %}
+    <div id="djact-loading" aria-hidden="true" style="display:none"></div>
+    {% endblock %}
+
+    {#
+      ── React mount point ────────────────────────────────────────────────
+
+      `data-page` carries the full JSON payload:
+        {
+          "component": "library/Dashboard",
+          "props":     { ... },
+          "url":       "/current/path/"
+        }
+
+      The value is produced by djact.render._safe_json() which escapes
+      < > & ' " so the string is safe to embed in any HTML attribute
+      context.  We still add |safe to prevent Django's auto-escape from
+      double-encoding the already-escaped output.
+    #}
+    <div id="app" data-page="{{ page|safe }}"></div>
+
+    {#
+      ── Djact client bundle ──────────────────────────────────────────────
+
+      Loaded as type="module":
+        • Deferred (runs after DOM is parsed — no need for DOMContentLoaded).
+        • Enables top-level await and native ESM imports.
+        • Scoped — no global namespace pollution.
+
+      In production, replace this with your bundled output and use
+      {% static 'djact/app.min.js' %} or your asset manifest hash.
+    #}
+    <script type="module" src="{% static 'djact/app.js' %}"></script>
+
+    {# ── Extra scripts / analytics injected by child templates ──────────── #}
+    {% block scripts %}{% endblock %}
+
+  </body>
+</html>

djact/utils.py

@@ -0,0 +1,23 @@
+"""
+djact.utils
+~~~~~~~~~~~
+Internal utility helpers shared across the package.
+"""
+
+# Django normalises HTTP headers: uppercase, hyphens → underscores, HTTP_ prefix.
+_DJACT_META_KEY = "HTTP_X_DJACT"
+
+
+def is_djact_request(request) -> bool:
+    """Return True when the request carries the X-Djact header."""
+    return _DJACT_META_KEY in request.META
+
+
+def get_csrf_token(request) -> str | None:
+    """Return the CSRF token for the current request, or None on failure."""
+    try:
+        from django.middleware.csrf import get_token
+
+        return get_token(request)
+    except Exception:
+        return None

djact-1.0.0.dist-info/METADATA

@@ -0,0 +1,384 @@
+Metadata-Version: 2.4
+Name: djact
+Version: 1.0.0
+Summary: Inertia.js-like bridge between Django and React — server-driven SPA without a REST API.
+License: MIT License
+        
+        Copyright (c) 2024 djact contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/yourusername/djact
+Project-URL: Repository, https://github.com/yourusername/djact
+Project-URL: Bug Tracker, https://github.com/yourusername/djact/issues
+Keywords: django,react,inertia,spa,frontend,bridge
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.0
+Classifier: Framework :: Django :: 4.1
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=4.0
+Dynamic: license-file
+
+# djact ⚛️🐍
+
+Welcome to **djact**! This is a complete, step-by-step guide to building your first project using Django and React without the headache of APIs.
+
+---
+
+## 1. What is Djact?
+
+Think of **djact** as a bridge.
+
+- **Django** handles the "Brain": It manages your database, users, and page logic.
+- **React** handles the "Beauty": It renders the user interface (UI) and makes it feel fast.
+- **No REST API Needed**: You don't need to build complex endpoints. You just pass data from Django to React like you would with a normal template.
+- **SPA Feel**: Your app feels like a Single Page Application (fast and fluid) because Djact only swaps the content of the page when you click a link.
+
+## 2. Installation
+
+```bash
+pip install djact
+```
+
+## 3. Create your Django Project
+
+Let's start a fresh project from scratch.
+
+```bash
+# Create the project folder
+django-admin startproject myproject
+
+# Go inside the project
+cd myproject
+
+# Create an app called "core"
+python manage.py startapp core
+```
+
+**What just happened?**
+You now have a folder named `myproject` containing your project settings and an app named `core` where we will write our code.
+
+---
+
+## 4. Django Setup
+
+Open `myproject/settings.py` and make these changes:
+
+### Add to `INSTALLED_APPS`
+Tell Django to use `djact` and your new `core` app.
+
+```python
+INSTALLED_APPS = [
+    ...
+    "djact",
+    "core",
+]
+```
+
+### Add Middleware
+Middleware is code that runs on every request. This allows Djact to detect when a user is navigating.
+
+```python
+MIDDLEWARE = [
+    ...
+    "djact.middleware.DjactMiddleware",
+]
+```
+
+---
+
+## 5. Create a View
+
+In Django, a "View" is the function that handles a specific URL.
+
+Open `core/views.py` and paste this:
+
+```python
+from djact import djact_render
+
+def home(request):
+    return djact_render(request, "Home", {
+        "name": "Ankur"
+    })
+```
+
+**Explanation:**
+We are telling Django to render a React component named **"Home"** and pass it a prop named `name` with the value `"Ankur"`.
+
+---
+
+## 6. Create URLs
+
+We need to tell Django which URL should trigger our view.
+
+### Step 1: Create `core/urls.py`
+Create a new file at `core/urls.py` and add:
+
+```python
+from django.urls import path
+from .views import home
+
+urlpatterns = [
+    path("", home, name="home"),
+]
+```
+
+### Step 2: Update `myproject/urls.py`
+Update your project's main URL file to include the one we just made:
+
+```python
+from django.urls import path, include
+
+urlpatterns = [
+    path("", include("core.urls")),
+]
+```
+
+---
+
+## 7. Template Setup
+
+Djact needs one basic HTML file to "mount" React.
+
+1. Create a folder named `templates` in your project root.
+2. Inside `templates`, create a file named `djact.html`.
+
+### File: `templates/djact.html`
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="csrf-token" content="{{ csrf_token }}">
+    <title>My Djact App</title>
+</head>
+<body>
+    <!-- React will mount inside this div -->
+    <div id="app" data-page='{{ page|safe }}'></div>
+
+    <!-- This is your bundled React JavaScript -->
+    <script type="module" src="/static/dist/main.js"></script>
+</body>
+</html>
+```
+
+**Why is this needed?**
+This is the "shell". Django loads this file once, and then React takes over the `div#app`. The `data-page` attribute is how Django "sends" the initial props to React.
+
+---
+
+## 8. React Setup
+
+Now let's set up the frontend using Vite.
+
+```bash
+# In your project root, run:
+npm create vite@latest frontend -- --template react
+
+# Go into the frontend folder
+cd frontend
+
+# Install dependencies
+npm install
+```
+
+---
+
+## 9. The Bridge: `main.jsx`
+
+This is the most important file in the frontend. It connects Django to React.
+
+Open `frontend/src/main.jsx` and replace everything with:
+
+```jsx
+import { createDjactApp } from "djact/static/djact/app.js";
+
+createDjactApp({
+  resolve: (name) => import(`./Pages/${name}.jsx`),
+});
+```
+
+**What is happening here?**
+- `createDjactApp`: This is the Djact engine. It reads the `data-page` from the HTML we created in Step 7.
+- `resolve`: This function tells Djact where to find your React files. When Django says "Render Home", Djact looks for `./Pages/Home.jsx`.
+
+---
+
+## 10. Create React Pages
+
+Create a folder named `Pages` inside `frontend/src/`. Then create your first page.
+
+### File: `frontend/src/Pages/Home.jsx`
+
+```jsx
+export default function Home({ name }) {
+    return (
+        <div style={{ padding: '2rem', textAlign: 'center' }}>
+            <h1>Hello {name}!</h1>
+            <p>Welcome to your Djact application.</p>
+        </div>
+    );
+}
+```
+
+**Note:** The `name` prop comes directly from the Django view we wrote in Step 5!
+
+---
+
+## 11. Build React
+
+Before Django can see your React code, you must build it.
+
+In your `frontend` folder, open `vite.config.js` and set the build output to your Django static folder:
+
+```javascript
+// vite.config.js
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    outDir: '../static/dist', // Build directly into Django's static folder
+    rollupOptions: {
+      output: {
+        entryFileNames: `[name].js`,
+        chunkFileNames: `[name].js`,
+        assetFileNames: `[name].[ext]`,
+      },
+    },
+  },
+})
+```
+
+Now run the build:
+```bash
+npm run build
+```
+
+---
+
+## 12. Run the Project
+
+Go back to your project root (where `manage.py` is) and start the server:
+
+```bash
+python manage.py runserver
+```
+
+Open your browser and visit: **http://127.0.0.1:8000/**
+
+You should see **"Hello Ankur!"**
+
+---
+
+## 13. Navigation (Moving between pages)
+
+To move between pages without a full reload, use the `<Link>` component.
+
+```jsx
+import { Link } from "djact/static/djact/app.js";
+
+export default function Home({ name }) {
+    return (
+        <div>
+            <h1>Hello {name}</h1>
+            <Link href="/about">Go to About Page</Link>
+        </div>
+    );
+}
+```
+
+**How it works:**
+When you click the Link, Djact tells Django "Hey, I need the About page data". Django sends back the props, and React swaps the component instantly.
+
+---
+
+## 14. Full Project Structure
+
+This is what your project should look like:
+
+```text
+myproject/
+├── core/
+│   ├── urls.py
+│   └── views.py
+├── myproject/
+│   ├── settings.py
+│   └── urls.py
+├── templates/
+│   └── djact.html
+├── static/
+│   └── dist/ (Generated by npm run build)
+├── frontend/
+│   ├── src/
+│   │   ├── Pages/
+│   │   │   └── Home.jsx
+│   │   └── main.jsx
+│   └── vite.config.js
+└── manage.py
+```
+
+---
+
+## 15. Common Questions
+
+**Q: Where should I write my React code?**
+A: Inside `frontend/src/Pages/`. Each file should match the name you use in `djact_render`.
+
+**Q: Do I need React Router?**
+A: **No.** Django handles all the routes in `urls.py`.
+
+**Q: Why do I need to run `npm run build`?**
+A: Browsers cannot read `.jsx` files directly. The build step converts them into a single `.js` file that the browser understands.
+
+**Q: Can I use multiple Django apps?**
+A: Yes! You can organize your pages however you like. Just make sure your `resolve` function in `main.jsx` can find them.
+
+---
+
+## 16. Common Mistakes to Avoid
+
+1. **Forgetting to Build**: If you change your React code, you must run `npm run build` (or run Vite in watch mode) for Django to see the changes.
+2. **Missing Middleware**: If you get a "Page not found" error or the link reloads the whole page, check if `DjactMiddleware` is in `settings.py`.
+3. **Wrong Static Path**: Make sure the `<script>` tag in `djact.html` matches where Vite is building your files.
+
+---
+
+## 📄 License
+
+MIT

djact-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+djact/__init__.py,sha256=a2h2gxoVptAtTpoCVQAmrq9rH-t2VL2Ifw5YssvkgGA,223
+djact/apps.py,sha256=J1mamxu8DenwwRKC77m6iBGzkn_ZMnUHH-QYu7Rt9_Q,257
+djact/middleware.py,sha256=vM2r6n9Nwz0TjFeqAQNEx6wVkIWYAA1_xq3HKUvcE3I,1554
+djact/py.typed,sha256=PFDWdul5xFEGkC3SiF1iIpFSbukOZFXpF9fr3hGb67M,75
+djact/render.py,sha256=b4scQLNAWldm2l0aljwVVk_UUuNEo27I5EUJRgYEzDI,3151
+djact/utils.py,sha256=NebLuFZQ0OqFH7W9JD2i21porn5N62PQBW8kGi7aNYQ,614
+djact/static/djact/app.js,sha256=N2Yqyo04_V-E6ze8oonZxFLi2OY5cjvtMYT0HKp_4po,19927
+djact/templates/djact/djact.html,sha256=ecFZIU1Kuj1o3zH_0d_74UjQ4o0nAM2_8yQFcL2Cjw8,3392
+djact-1.0.0.dist-info/licenses/LICENSE,sha256=osNGSMuNQvuZnWRBvRk4zmOJpGedlyTmKmx7miWkS5c,1075
+djact-1.0.0.dist-info/METADATA,sha256=9yc-le3uyaM-AqTgFd1j4VNOp3kZRq2qMnchhaMl3LA,10330
+djact-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+djact-1.0.0.dist-info/top_level.txt,sha256=R8hM28vvmCfuRcaHtLOoNj5uz15XQ985ocSElI2CQV0,6
+djact-1.0.0.dist-info/RECORD,,

djact-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

djact-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 djact contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

djact-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+djact