add jumbo params and links in docs

Directory.Build.props

@@ -1,7 +1,7 @@
 <Project>
 
     <PropertyGroup>
-        <Version>0.4.1</Version>
+        <Version>0.5.0</Version>
         <Company>Code Happy, LLC</Company>
         <Authors>Code Happy, LLC</Authors>
         <Product>HTML/CSS To Image API</Product>

src/HtmlCssToImage/Client/HtmlCssToImageClient.Urls.cs

@@ -1,5 +1,6 @@
 using System.Buffers;
 using System.Diagnostics.CodeAnalysis;
+using System.Numerics;
 using System.Text.Json;
 using System.Text.Json.Nodes;
 using System.Text.Json.Serialization.Metadata;
@@ -105,74 +106,67 @@ internal static void CreateAndRenderUrlQueryString(CreateUrlImageRequest request
     {
         QueryStringEncoder.EncodeSafeKey("url", request.Url, ref chars);
 
-        if (request.FullScreen == true)
-        {
-            QueryStringEncoder.EncodeSafeKeyValue("full_screen", "true", ref chars);
-        }
-
-        if (request.BlockConsentBanners == true)
-        {
-            QueryStringEncoder.EncodeSafeKeyValue("block_consent_banners", "true", ref chars);
-        }
-
-        if (request.DisableTwemoji == true)
-        {
-            QueryStringEncoder.EncodeSafeKeyValue("disable_twemoji", "true", ref chars);
-        }
-
-        if (request.MaxRenderOnce == true)
-        {
-            QueryStringEncoder.EncodeSafeKeyValue("max_render_once", "true", ref chars);
-        }
-
-        if (request.RenderWhenReady == true)
-        {
-            QueryStringEncoder.EncodeSafeKeyValue("render_when_ready", "true", ref chars);
-        }
+        AppendBoolIfTrue("full_screen",request.FullScreen, ref chars);
+        AppendBoolIfTrue("block_consent_banners",request.BlockConsentBanners, ref chars);
+        AppendBoolIfTrue("disable_twemoji",request.DisableTwemoji, ref chars);
+        AppendBoolIfTrue("max_render_once",request.MaxRenderOnce, ref chars);
+        AppendBoolIfTrue("render_when_ready",request.RenderWhenReady, ref chars);
 
         if (request.ColorScheme != null)
         {
-            QueryStringEncoder.EncodeSafeKeyValue("color_scheme", Helpers.EnumToString.ColorSchemeString(request.ColorScheme.Value), ref chars);
+            QueryStringEncoder.EncodeSafeKeyValue("color_scheme", request.ColorScheme.Value.ColorSchemeString(), ref chars);
         }
+        AppendNumberIfNotNull("device_scale", request.DeviceScale, ref chars);
+        AppendNumberIfNotNull("max_wait_ms", request.MaxWaitMs, ref chars);
+        AppendNumberIfNotNull("ms_delay", request.MsDelay, ref chars);
+        AppendNumberIfNotNull("viewport_height", request.ViewportHeight, ref chars);
+        AppendNumberIfNotNull("viewport_width", request.ViewportWidth, ref chars);
 
-        if (request.DeviceScale != null)
+        if (!string.IsNullOrWhiteSpace(request.Css))
         {
-            QueryStringEncoder.WriteSafeKey("device_scale", request.DeviceScale.Value, ref chars);
+            QueryStringEncoder.EncodeSafeKey("css", request.Css, ref chars);
         }
 
-        if (request.MaxWaitMs != null)
+        if (!string.IsNullOrWhiteSpace(request.Selector))
         {
-            QueryStringEncoder.WriteSafeKey("max_wait_ms", request.MaxWaitMs.Value, ref chars);
+            QueryStringEncoder.EncodeSafeKey("selector", request.Selector, ref chars);
         }
 
-        if (request.MsDelay != null)
+        if (!string.IsNullOrWhiteSpace(request.Timezone))
         {
-            QueryStringEncoder.WriteSafeKey("ms_delay", request.MsDelay.Value, ref chars);
+            QueryStringEncoder.EncodeSafeKey("timezone", request.Timezone, ref chars);
         }
-
-        if (request.ViewportHeight != null)
+        AppendBoolIfTrue("viewport_mobile", request.ViewportMobile, ref chars);
+        AppendBoolIfTrue("viewport_landscape", request.ViewportLandscape, ref chars);
+        AppendBoolIfTrue("viewport_touch", request.ViewportTouch, ref chars);
+        if (request.MediaType != null)
         {
-            QueryStringEncoder.WriteSafeKey("viewport_height", request.ViewportHeight.Value, ref chars);
+            QueryStringEncoder.EncodeSafeKeyValue("media_type", request.MediaType.Value.MediaTypeString(), ref chars);
         }
 
-        if (request.ViewportWidth != null)
+        if (!string.IsNullOrWhiteSpace(request.ProxyId))
         {
-            QueryStringEncoder.WriteSafeKey("viewport_width", request.ViewportWidth.Value, ref chars);
+            QueryStringEncoder.EncodeSafeKey("proxy_id", request.ProxyId, ref chars);
         }
 
-        if (!string.IsNullOrWhiteSpace(request.Css))
-        {
-            QueryStringEncoder.EncodeSafeKey("css", request.Css, ref chars);
-        }
+        AppendNumberIfNotNull("jumbo_max_width", request.JumboMaxWidth, ref chars);
+        AppendNumberIfNotNull("jumbo_max_height", request.JumboMaxHeight, ref chars);
 
-        if (!string.IsNullOrWhiteSpace(request.Selector))
+    }
+
+    private static void AppendNumberIfNotNull<T>(ReadOnlySpan<char> key, T? value, ref ArrayOrSpan<char> chars) where T : struct, INumber<T>
+    {
+        if (value != null)
         {
-            QueryStringEncoder.EncodeSafeKey("selector", request.Selector, ref chars);
+            QueryStringEncoder.WriteSafeKey(key, value.Value, ref chars);
         }
+    }
 
-        if (!string.IsNullOrWhiteSpace(request.Timezone))
+    private static void AppendBoolIfTrue(ReadOnlySpan<char> key, bool? value, ref ArrayOrSpan<char> chars)
+    {
+        if (value == true)
         {
-            QueryStringEncoder.EncodeSafeKey("timezone", request.Timezone, ref chars);
+            QueryStringEncoder.EncodeSafeKeyValue(key, "true", ref chars);
         }
     }
 

src/HtmlCssToImage/Helpers/EnumToString.cs

@@ -6,10 +6,18 @@ namespace HtmlCssToImage.Helpers;
 internal static class EnumToString
 {
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    internal static string ColorSchemeString(ColorSchemeType type) => type switch
+    internal static string ColorSchemeString(this ColorSchemeType type) => type switch
     {
         ColorSchemeType.dark  => nameof(ColorSchemeType.dark),
         ColorSchemeType.light => nameof(ColorSchemeType.light),
         _                     => throw new ArgumentOutOfRangeException(nameof(type), type, null)
     };
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    internal static string MediaTypeString(this MediaType type) => type switch
+    {
+        MediaType.screen => nameof(MediaType.screen),
+        MediaType.print  => nameof(MediaType.print),
+        _                => throw new ArgumentOutOfRangeException(nameof(type), type, null)
+    };
 }

src/HtmlCssToImage/Models/Requests/CreateHtmlCssImageRequest.cs

@@ -25,6 +25,7 @@ public class CreateHtmlCssImageRequest:CreateImageCommonOptions, IBatchAllowedIm
     /// Gets or sets the Google Fonts to be included when generating an image.
     /// This property allows specifying one or more Google Fonts
     /// You must also set the font-family in your CSS to use the loaded font(s).
+    /// <see href="https://docs.htmlcsstoimage.com/parameters/google_fonts/">Read the Google Fonts Guide for more information.</see>
     /// </summary>
     [JsonConverter(typeof(GoogleFontsJsonConverter))]
     public string[]? GoogleFonts { get; set; }

src/HtmlCssToImage/Models/Requests/CreateImageCommonOptions.cs

@@ -11,88 +11,105 @@ namespace HtmlCssToImage.Models.Requests;
 [JsonDerivedType(typeof(CreateUrlImageRequest))]
 public abstract class CreateImageCommonOptions
 {
-        /// <summary>
-        /// A CSS selector to target a specific element on the page. The API will crop the image to the dimensions of this element.
-        /// </summary>
-        public string? Selector { get; set; }
-
-        /// <summary>
-        /// Adjusts the pixel ratio for the screenshot. The default is 2 which is equivalent to a 4K monitor.
-        /// </summary>
-        public double? DeviceScale { get; set; }
-
-        /// <summary>
-        /// Set the height of Chrome's viewport. This will disable automatic cropping.
-        /// </summary>
-        public uint? ViewportHeight { get; set; }
-
-        /// <summary>
-        /// Set the width of Chrome's viewport. This will disable automatic cropping.
-        /// </summary>
-        public uint? ViewportWidth { get; set; }
-
-        /// <summary>
-        /// Sets a limit on time to wait until the screenshot is taken. Use this if your page loads a lot of extra irrelevant content, and you want to reduce the render time.
-        /// </summary>
-        public uint? MaxWaitMs { get; set; }
-
-        /// <summary>
-        /// Adds extra time before taking the screenshot, like if you need to wait for Javascript to execute
-        /// </summary>
-        public uint? MsDelay { get; set; }
-
-        /// <summary>
-        /// This will wait until 'ScreenshotReady()' is called from Javascript to take the screenshot.
-        /// </summary>
-        public bool? RenderWhenReady { get; set; }
-
-        /// <summary>
-        /// Ensure the image is only ever rendered and saved one time. This is an advanced option not applicable to most scenarios.
-        /// </summary>
-        public bool? MaxRenderOnce { get; set; }
-
-        /// <summary>
-        /// Twemoji is used to render emoji as a fallback for native emoji fonts. This option will disable that behavior.
-        /// </summary>
-        public bool? DisableTwemoji { get; set; }
-
-        /// <summary>
-        /// Options for generating a PDF from the HTML/CSS.
-        /// </summary>
-        public PDFOptions? PDFOptions { get; set; }
-
-        /// <summary>
-        /// Set Chrome to render assuming the user has explicitly set their browser to Light or Dark mode.
-        /// </summary>
-        public ColorSchemeType? ColorScheme { get; set; }
-
-        /// <summary>
-        /// Sets the timezone for the browser instance. Use IANA timezone format (e.g. 'America/New_York').
-        /// </summary>
-        public string? Timezone { get; set; }
-
-        /// <summary>
-        /// Gets or sets a value indicating whether the viewport should be rendered as if it's being viewed from a mobile device.
-        /// </summary>
-        public bool? ViewportMobile { get; set; }
-
-        /// <summary>
-        /// Gets or sets a value indicating whether the viewport should be in landscape orientation.
-        /// </summary>
-        public bool? ViewportLandscape { get; set; }
-
-        /// <summary>
-        /// Gets or sets a value indicating whether touch interactions are enabled within the viewport.
-        /// </summary>
-        public bool? ViewportTouch { get; set; }
-        /// <summary>
-        /// Gets or sets the media type to use for rendering.
-        /// </summary>
-        public MediaType? MediaType { get; set; }
-
-        /// <summary>
-        /// Gets or sets the proxy ID to use for rendering.
-        /// </summary>
-        public string? ProxyId { get; set; }
-
+    /// <summary>
+    /// A CSS selector to target a specific element on the page. The API will crop the image to the dimensions of this element.
+    /// <see href="https://docs.htmlcsstoimage.com/parameters/selector/">Read the selector Guide for more information.</see>
+    /// </summary>
+    public string? Selector { get; set; }
+
+    /// <summary>
+    /// Adjusts the pixel ratio for the screenshot. The default is 2 which is equivalent to a 4K monitor.
+    /// <see href="https://docs.htmlcsstoimage.com/parameters/device_scale/">Read the device_scale Guide for more information.</see>
+    /// </summary>
+    public double? DeviceScale { get; set; }
+
+    /// <summary>
+    /// Set the height of Chrome's viewport. This will disable automatic cropping.
+    /// </summary>
+    public uint? ViewportHeight { get; set; }
+
+    /// <summary>
+    /// Set the width of Chrome's viewport. This will disable automatic cropping.
+    /// </summary>
+    public uint? ViewportWidth { get; set; }
+
+    /// <summary>
+    /// Sets a limit on time to wait until the screenshot is taken. Use this if your page loads a lot of extra irrelevant content, and you want to reduce the render time.
+    /// </summary>
+    public uint? MaxWaitMs { get; set; }
+
+    /// <summary>
+    /// Adds extra time before taking the screenshot, like if you need to wait for Javascript to execute
+    /// <see href="https://docs.htmlcsstoimage.com/parameters/ms_delay/">See the ms_delay docs for more information.</see>
+    /// </summary>
+    public uint? MsDelay { get; set; }
+
+    /// <summary>
+    /// This will wait until 'ScreenshotReady()' is called from Javascript to take the screenshot.
+    /// <see href="https://docs.htmlcsstoimage.com/parameters/render_when_ready/">Read the Render When Ready Guide for more information.</see>
+    /// </summary>
+    public bool? RenderWhenReady { get; set; }
+
+    /// <summary>
+    /// Ensure the image is only ever rendered and saved one time. This is an advanced option not applicable to most scenarios.
+    /// </summary>
+    public bool? MaxRenderOnce { get; set; }
+
+    /// <summary>
+    /// Twemoji is used to render emoji as a fallback for native emoji fonts. This option will disable that behavior.
+    /// </summary>
+    public bool? DisableTwemoji { get; set; }
+
+    /// <summary>
+    /// Options for generating a PDF from the HTML/CSS.
+    /// </summary>
+    public PDFOptions? PDFOptions { get; set; }
+
+    /// <summary>
+    /// Set Chrome to render assuming the user has explicitly set their browser to Light or Dark mode.
+    /// <see href="https://docs.htmlcsstoimage.com/parameters/color_scheme/">Read the color_scheme Guide for more information.</see>        /// </summary>
+    public ColorSchemeType? ColorScheme { get; set; }
+
+    /// <summary>
+    /// Sets the timezone for the browser instance. Use IANA timezone format (e.g. 'America/New_York').
+    /// </summary>
+    public string? Timezone { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the viewport should be rendered as if it's being viewed from a mobile device.
+    /// </summary>
+    public bool? ViewportMobile { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the viewport should be in landscape orientation.
+    /// </summary>
+    public bool? ViewportLandscape { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether touch interactions are enabled within the viewport.
+    /// </summary>
+    public bool? ViewportTouch { get; set; }
+
+    /// <summary>
+    /// Gets or sets the media type to use for rendering.
+    /// </summary>
+    public MediaType? MediaType { get; set; }
+
+    /// <summary>
+    /// Gets or sets the proxy ID to use for rendering.
+    /// <see href="https://docs.htmlcsstoimage.com/guides/advanced/proxies/">Read the Proxy Guide for more information.</see>
+    /// </summary>
+    public string? ProxyId { get; set; }
+
+    /// <summary>
+    /// Gets or sets the maximum width of the rendered image in jumbo mode. Consumes extra renders, requires <see cref="JumboMaxHeight"/> to be defined as well.
+    /// <see href="https://docs.htmlcsstoimage.com/guides/advanced/jumbo-images/"> Read the Jumbo Images Guide for more information.</see>
+    /// </summary>
+    public uint? JumboMaxWidth { get; set; }
+
+    /// <summary>
+    /// Gets or sets the maximum height of the rendered image in jumbo mode. Consumes extra renders, requires <see cref="JumboMaxWidth"/> to be defined as well.
+    /// <see href="https://docs.htmlcsstoimage.com/guides/advanced/jumbo-images/"> Read the Jumbo Images Guide for more information.</see>
+    /// </summary>
+    public uint? JumboMaxHeight { get; set; }
 }