litestar-vite 0.1.1__py3-none-any.whl → 0.15.0__py3-none-any.whl

litestar_vite/config/_constants.py

@@ -0,0 +1,97 @@
+"""Constants and utility functions for configuration."""
+
+from importlib.util import find_spec
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = (
+    "FSSPEC_INSTALLED",
+    "JINJA_INSTALLED",
+    "TRUE_VALUES",
+    "PaginationContainer",
+    "default_content_types",
+    "default_storage_options",
+    "empty_dict_factory",
+    "empty_set_factory",
+)
+
+TRUE_VALUES = {"True", "true", "1", "yes", "Y", "T"}
+JINJA_INSTALLED = bool(find_spec("jinja2"))
+FSSPEC_INSTALLED = bool(find_spec("fsspec"))
+
+
+@runtime_checkable
+class PaginationContainer(Protocol):
+    """Protocol for pagination containers that can be unwrapped for Inertia scroll.
+
+    Any type that has `items` and pagination metadata can implement this protocol.
+    The response will extract items and calculate scroll_props automatically.
+
+    Built-in support:
+    - litestar.pagination.OffsetPagination
+    - litestar.pagination.ClassicPagination
+    - advanced_alchemy.service.OffsetPagination
+
+    Custom types can implement this protocol::
+
+        @dataclass
+        class MyPagination:
+            items: list[T]
+            total: int
+            limit: int
+            offset: int
+    """
+
+    items: "Sequence[Any]"
+
+
+def empty_dict_factory() -> dict[str, Any]:
+    """Return an empty ``dict[str, Any]``.
+
+    Returns:
+        An empty dictionary.
+    """
+    return {}
+
+
+def empty_set_factory() -> set[str]:
+    """Return an empty ``set[str]``.
+
+    Returns:
+        An empty set.
+    """
+    return set()
+
+
+def default_content_types() -> dict[str, str]:
+    """Default content-type mappings keyed by file extension.
+
+    Returns:
+        Dictionary mapping file extensions to MIME types.
+    """
+    return {
+        ".js": "application/javascript",
+        ".mjs": "application/javascript",
+        ".cjs": "application/javascript",
+        ".css": "text/css",
+        ".html": "text/html",
+        ".json": "application/json",
+        ".svg": "image/svg+xml",
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".webp": "image/webp",
+        ".woff2": "font/woff2",
+        ".woff": "font/woff",
+    }
+
+
+def default_storage_options() -> dict[str, Any]:
+    """Return an empty storage options dictionary.
+
+    Returns:
+        An empty dictionary.
+    """
+    return {}

litestar_vite/config/_deploy.py

@@ -0,0 +1,70 @@
+"""CDN deployment configuration."""
+
+import os
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+from litestar_vite.config._constants import TRUE_VALUES, default_content_types, default_storage_options
+
+__all__ = ("DeployConfig",)
+
+
+@dataclass
+class DeployConfig:
+    """CDN deployment configuration.
+
+    Attributes:
+        enabled: Enable deployment features.
+        storage_backend: fsspec URL for the target location (e.g., ``gcs://bucket/path``).
+        storage_options: Provider options forwarded to ``fsspec`` (credentials, region, etc.).
+        asset_url: Public URL prefix where deployed assets will be served (e.g., ``https://cdn.example.com/assets/``).
+            When set and deployment is enabled, this value is written to ``.litestar.json`` as ``deployAssetUrl`` and
+            used by the Vite plugin as the ``base`` during ``vite build``. It does not replace ``PathConfig.asset_url``.
+        delete_orphaned: Remove remote files not present in the local bundle.
+        include_manifest: Upload ``manifest.json`` alongside assets.
+        content_types: Optional content-type overrides keyed by file extension.
+    """
+
+    enabled: bool = True
+    storage_backend: "str | None" = field(default_factory=lambda: os.getenv("VITE_DEPLOY_STORAGE"))
+    storage_options: dict[str, Any] = field(default_factory=default_storage_options)
+    asset_url: "str | None" = field(default_factory=lambda: os.getenv("VITE_DEPLOY_ASSET_URL"))
+    delete_orphaned: bool = field(default_factory=lambda: os.getenv("VITE_DEPLOY_DELETE", "true") in TRUE_VALUES)
+    include_manifest: bool = True
+    content_types: dict[str, str] = field(default_factory=default_content_types)
+
+    def __post_init__(self) -> None:
+        """Apply environment fallbacks."""
+        if self.storage_backend is None:
+            self.storage_backend = os.getenv("VITE_DEPLOY_STORAGE")
+        if self.asset_url is None:
+            self.asset_url = os.getenv("VITE_DEPLOY_ASSET_URL")
+
+        if self.asset_url and self.asset_url != "/" and not self.asset_url.endswith("/"):
+            self.asset_url = f"{self.asset_url}/"
+
+    def with_overrides(
+        self,
+        storage_backend: "str | None" = None,
+        storage_options: "dict[str, Any] | None" = None,
+        asset_url: "str | None" = None,
+        delete_orphaned: "bool | None" = None,
+    ) -> "DeployConfig":
+        """Return a copy with overrides applied.
+
+        Args:
+            storage_backend: Override for the storage URL.
+            storage_options: Override for backend options.
+            asset_url: Override for the public asset URL.
+            delete_orphaned: Override deletion behaviour.
+
+        Returns:
+            DeployConfig copy with updated fields.
+        """
+        return replace(
+            self,
+            storage_backend=storage_backend or self.storage_backend,
+            storage_options=storage_options or self.storage_options,
+            asset_url=asset_url or self.asset_url,
+            delete_orphaned=self.delete_orphaned if delete_orphaned is None else delete_orphaned,
+        )

litestar_vite/config/_inertia.py

@@ -0,0 +1,241 @@
+"""Inertia.js configuration classes."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from litestar_vite.config._constants import empty_dict_factory, empty_set_factory
+
+__all__ = ("InertiaConfig", "InertiaSSRConfig", "InertiaTypeGenConfig")
+
+
+@dataclass
+class InertiaSSRConfig:
+    """Server-side rendering settings for Inertia.js.
+
+    Inertia SSR runs a separate Node server that renders the initial HTML for an
+    Inertia page object. Litestar sends the page payload to the SSR server (by
+    default at ``http://127.0.0.1:13714/render``) and injects the returned head
+    tags and body markup into the HTML response.
+
+    Notes:
+        - This is *not* Litestar-Vite's framework proxy mode (``mode="framework"``; aliases: ``mode="ssr"`` / ``mode="ssg"``).
+        - When enabled, failures to contact the SSR server are treated as errors (no silent fallback).
+    """
+
+    enabled: bool = True
+    url: str = "http://127.0.0.1:13714/render"
+    timeout: float = 2.0
+
+
+@dataclass
+class InertiaConfig:
+    """Configuration for InertiaJS support.
+
+    This is the canonical configuration class for Inertia.js integration.
+    Presence of an InertiaConfig instance indicates Inertia is enabled.
+
+    Note:
+        SPA mode (HTML transformation vs Jinja2 templates) is controlled by
+        ViteConfig.mode='hybrid'. The app_selector for data-page injection
+        is configured via SPAConfig.app_selector.
+
+    Attributes:
+        root_template: Name of the root template to use.
+        component_opt_keys: Identifiers for getting inertia component from route opts.
+        redirect_unauthorized_to: Path for unauthorized request redirects.
+        redirect_404: Path for 404 request redirects.
+        extra_static_page_props: Static props added to every page response.
+        extra_session_page_props: Session keys to include in page props.
+    """
+
+    root_template: str = "index.html"
+    """Name of the root template to use.
+
+    This must be a path that is found by the Vite Plugin template config
+    """
+    component_opt_keys: "tuple[str, ...]" = ("component", "page")
+    """Identifiers to use on routes to get the inertia component to render.
+
+    The first key found in the route handler opts will be used. This allows
+    semantic flexibility - use "component" or "page" depending on preference.
+
+    Example:
+        # All equivalent:
+        @get("/", component="Home")
+        @get("/", page="Home")
+
+        # Custom keys:
+        InertiaConfig(component_opt_keys=("view", "component", "page"))
+    """
+    redirect_unauthorized_to: "str | None" = None
+    """Optionally supply a path where unauthorized requests should redirect."""
+    redirect_404: "str | None" = None
+    """Optionally supply a path where 404 requests should redirect."""
+    extra_static_page_props: "dict[str, Any]" = field(default_factory=empty_dict_factory)
+    """A dictionary of values to automatically add in to page props on every response."""
+    extra_session_page_props: "set[str] | dict[str, type]" = field(default_factory=empty_set_factory)
+    """Session props to include in page responses.
+
+    Can be either:
+    - A set of session key names (types will be 'unknown')
+    - A dict mapping session keys to Python types (auto-registered with OpenAPI)
+
+    Example with types (recommended):
+        extra_session_page_props={"currentTeam": TeamDetail}
+
+    Example without types (legacy):
+        extra_session_page_props={"currentTeam"}
+    """
+    encrypt_history: bool = False
+    """Enable browser history encryption globally (v2 feature).
+
+    When True, all Inertia responses will include `encryptHistory: true`
+    in the page object. The Inertia client will encrypt history state
+    using browser's crypto API before pushing to history.
+
+    This prevents sensitive data from being visible in browser history
+    after a user logs out. Individual responses can override this setting.
+
+    Note: Encryption happens client-side; requires HTTPS in production.
+    See: https://inertiajs.com/history-encryption
+    """
+    type_gen: "InertiaTypeGenConfig | None" = None
+    """Type generation options for Inertia page props.
+
+    Controls default types in generated page-props.ts. Set to InertiaTypeGenConfig()
+    or leave as None for defaults. Use InertiaTypeGenConfig(include_default_auth=False)
+    to disable default User/AuthData interfaces for non-standard user models.
+    """
+
+    ssr: "InertiaSSRConfig | bool | None" = None
+    """Enable server-side rendering (SSR) for Inertia responses.
+
+    When enabled, full-page HTML responses will be pre-rendered by a Node SSR server
+    and injected into the SPA HTML before returning to the client.
+
+    Supports:
+        - True: enable with defaults -> ``InertiaSSRConfig()``
+        - False/None: disabled -> ``None``
+        - InertiaSSRConfig: use as-is
+    """
+
+    use_script_element: bool = False
+    """Use a script element instead of data-page attribute for page data.
+
+    When True, embeds page data in a ``<script type="application/json" id="app_page">``
+    element instead of a ``data-page`` attribute on the app element.
+
+    Benefits:
+        - ~37% payload reduction for large pages (no HTML entity escaping)
+        - Better performance for pages with complex props
+
+    Requirements:
+        - Client must also enable: ``createInertiaApp({ useScriptElementForInitialPage: true })``
+        - Requires Inertia.js v2.3+
+
+    Disabled by default for compatibility with existing Inertia clients.
+    """
+
+    precognition: bool = False
+    """Enable Precognition support for real-time form validation.
+
+    When True, registers an exception handler that converts validation errors
+    to Laravel's Precognition format when the Precognition header is present.
+    This enables real-time validation without executing handler side effects.
+
+    Usage:
+        1. Enable in config: InertiaConfig(precognition=True)
+        2. Use @precognition decorator on form handlers
+        3. Use laravel-precognition-vue/react on the frontend
+
+    Note on Rate Limiting:
+        Real-time validation can generate many requests. Consider:
+        - Frontend debouncing (built into laravel-precognition libraries)
+        - Server-side throttling for Precognition requests
+        - Laravel has no official rate limiting solution for Precognition
+
+    See: https://laravel.com/docs/precognition
+    """
+
+    def __post_init__(self) -> None:
+        """Normalize optional sub-configs."""
+        if self.ssr is True:
+            self.ssr = InertiaSSRConfig()
+        elif self.ssr is False:
+            self.ssr = None
+
+    @property
+    def ssr_config(self) -> "InertiaSSRConfig | None":
+        """Return the SSR config when enabled, otherwise None.
+
+        Returns:
+            The resolved SSR config when enabled, otherwise None.
+        """
+        if isinstance(self.ssr, InertiaSSRConfig) and self.ssr.enabled:
+            return self.ssr
+        return None
+
+
+@dataclass
+class InertiaTypeGenConfig:
+    """Type generation options for Inertia page props.
+
+    Controls which default types are included in the generated page-props.ts file.
+    This follows Laravel Jetstream patterns - sensible defaults for common auth patterns.
+
+    Attributes:
+        include_default_auth: Include default User and AuthData interfaces.
+            Default User has: id, email, name. Users extend via module augmentation.
+            Set to False if your User model doesn't have these fields (uses uuid, username, etc.)
+        include_default_flash: Include default FlashMessages interface.
+            Uses { [category: string]: string[] } pattern for flash messages.
+
+    Example:
+        Standard auth (95% of users) - just extend defaults::
+
+            # Python: use defaults
+            ViteConfig(inertia=InertiaConfig())
+
+            # TypeScript: extend User interface
+            declare module 'litestar-vite-plugin/inertia' {
+                interface User {
+                    avatarUrl?: string
+                    roles: Role[]
+                }
+            }
+
+        Custom auth (5% of users) - define from scratch::
+
+            # Python: disable defaults
+            ViteConfig(inertia=InertiaConfig(
+                type_gen=InertiaTypeGenConfig(include_default_auth=False)
+            ))
+
+            # TypeScript: define your custom User
+            declare module 'litestar-vite-plugin/inertia' {
+                interface User {
+                    uuid: string  // No id!
+                    username: string  // No email!
+                }
+            }
+    """
+
+    include_default_auth: bool = True
+    """Include default User and AuthData interfaces.
+
+    When True, generates:
+    - User: { id: string, email: string, name?: string | null }
+    - AuthData: { isAuthenticated: boolean, user?: User }
+
+    Users extend via TypeScript module augmentation.
+    Set to False if your User model has different required fields.
+    """
+
+    include_default_flash: bool = True
+    """Include default FlashMessages interface.
+
+    When True, generates:
+    - FlashMessages: { [category: string]: string[] }
+
+    Standard flash message pattern used by most web frameworks.
+    """

litestar_vite/config/_paths.py

@@ -0,0 +1,63 @@
+"""File system paths configuration."""
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+__all__ = ("PathConfig",)
+
+
+@dataclass
+class PathConfig:
+    """File system paths configuration.
+
+    Attributes:
+        root: The root directory of the project. Defaults to current working directory.
+        bundle_dir: Location of compiled assets and manifest.json.
+        resource_dir: TypeScript/JavaScript source directory (equivalent to ./src in Vue/React).
+        static_dir: Static public assets directory (served as-is by Vite).
+        manifest_name: Name of the Vite manifest file.
+        hot_file: Name of the hot file indicating dev server URL.
+        asset_url: Base URL for static asset references (prepended to Vite output).
+        ssr_output_dir: SSR output directory (optional).
+    """
+
+    root: "str | Path" = field(default_factory=Path.cwd)
+    bundle_dir: "str | Path" = field(default_factory=lambda: Path("public"))
+    resource_dir: "str | Path" = field(default_factory=lambda: Path("src"))
+    static_dir: "str | Path" = field(default_factory=lambda: Path("public"))
+    manifest_name: str = "manifest.json"
+    hot_file: str = "hot"
+    asset_url: str = field(default_factory=lambda: os.getenv("ASSET_URL", "/static/"))
+    ssr_output_dir: "str | Path | None" = None
+
+    def __post_init__(self) -> None:
+        """Normalize path types to Path objects.
+
+        This also adjusts defaults to prevent Vite's ``publicDir`` (input) from
+        colliding with ``outDir`` (output). ``bundle_dir`` is treated as the build
+        output directory. When ``static_dir`` equals ``bundle_dir``, Vite may warn
+        and effectively disable public asset copying, so ``static_dir`` defaults to
+        ``<resource_dir>/public`` in that case.
+        """
+        if isinstance(self.root, str):
+            object.__setattr__(self, "root", Path(self.root))
+        if isinstance(self.bundle_dir, str):
+            object.__setattr__(self, "bundle_dir", Path(self.bundle_dir))
+        if isinstance(self.resource_dir, str):
+            object.__setattr__(self, "resource_dir", Path(self.resource_dir))
+        if isinstance(self.static_dir, str):
+            object.__setattr__(self, "static_dir", Path(self.static_dir))
+        if isinstance(self.ssr_output_dir, str):
+            object.__setattr__(self, "ssr_output_dir", Path(self.ssr_output_dir))
+
+        if (
+            isinstance(self.bundle_dir, Path)
+            and isinstance(self.static_dir, Path)
+            and self.static_dir == self.bundle_dir
+        ):
+            object.__setattr__(self, "static_dir", Path(self.resource_dir) / "public")
+
+        asset_url = self.asset_url
+        if asset_url and asset_url != "/" and not asset_url.endswith("/"):
+            object.__setattr__(self, "asset_url", f"{asset_url}/")