PdfViewer: Password support (#68)

* PDF Viewer - Password support #67

Author: gvreddy04

BlazorExpress.Bulma.Demo.RCL/Constants/DemoStringConstants.cs

@@ -10,6 +10,7 @@ public static class DemoStringConstants
     public const string PageTitle_Suffix = " | Blazor Bulma: An enterprise-grade open-source component library from the Blazor Express team.";
 
     public const string StaticAssets_RootPath = "_content/BlazorExpress.Bulma.Demo.RCL";
+    public const string StaticAssets_Docs_Path = StaticAssets_RootPath + "/docs";
     public const string StaticAssets_Icons_Path = StaticAssets_RootPath + "/icons";
     public const string StaticAssets_Icons_Logo_png = StaticAssets_Icons_Path + "/logo.png";
 

BlazorExpress.Bulma.Demo.RCL/Pages/Demos/PdfViewer/PdfViewerDocumentation.razor

@@ -62,6 +62,42 @@
     <Demo Type="typeof(PdfViewer_Demo_03_Base64String)" Tabs="true" />
 </Section>
 
+<Section Class="p-0" Size="HeadingSize.H3" Name="Password Protected PDFs (Fixed Password)" PageUrl="@pageUrl" Link="password-protected-pdfs-fixed-password">
+    <Block>
+        The <strong>PdfViewer</strong> component supports opening password-protected PDF files by supplying a fixed password via the <code>Password</code> parameter.
+        <br /><br />
+        <strong>How to use:</strong>
+        <div class="content mb-2">
+            <ol>
+                <li>Add the <code>PdfViewer</code> component to your page.</li>
+                <li>Set the <code>Url</code> parameter to the protected PDF file (static URL or data URI).</li>
+                <li>Provide the document password using the <code>Password</code> parameter (example: <code>Password="12345"</code>).</li>
+                <li>Optionally handle <code>OnDocumentLoaded</code> and <code>OnPageChanged</code> to react after the document opens or when the user navigates pages.</li>
+            </ol>
+        </div>
+        The demo loads <code>pdf_password_protected.pdf</code> from static assets and demonstrates a fixed-password scenario: <code>Password="12345"</code>. Security note: do not hard-code production secrets into client-side WebAssembly. If the PDF password must remain secret, validate or supply it server-side or use a user prompt instead (see the "Prompt for Password" demo).
+    </Block>
+    <Demo Type="typeof(PdfViewer_Demo_04_Password_Protected_A)" Tabs="true" />
+</Section>
+
+<Section Class="p-0" Size="HeadingSize.H3" Name="password Protected PDFs (Prompt for Password)" PageUrl="@pageUrl" Link="password-protected-pdfs-prompt-for-password">
+    <Block>
+        The <strong>PdfViewer</strong> component can also be used in scenarios where you want the user to provide the password at runtime. Instead of setting a fixed <code>Password</code>, the component will prompt for credentials when a protected document is loaded (or you can implement your own prompt and pass the value to <code>Password</code>).
+        <br /><br />
+        <strong>How to use:</strong>
+        <div class="content mb-2">
+            <ol>
+                <li>Add the <code>PdfViewer</code> component to your page without setting the <code>Password</code> parameter.</li>
+                <li>Set the <code>Url</code> parameter to the protected PDF file.</li>
+                <li>Optionally delay or control loading (for example, show a <code>Button</code> that creates the viewer on demand) so the prompt appears only when appropriate.</li>
+                <li>Optionally implement a custom UI to collect a password and supply it to the component via the <code>Password</code> parameter if you need a tailored UX.</li>
+            </ol>
+        </div>
+        The demo demonstrates a lazy-load approach: a button toggles <code>showPdfViewer</code> and instantiates the viewer which then prompts for the password. This is useful when you want to avoid showing the prompt until the user explicitly requests the document.
+    </Block>
+    <Demo Type="typeof(PdfViewer_Demo_05_Password_Protected_B_Prompt_For_Password)" Tabs="true" />
+</Section>
+
 @code {
     private const string componentName = nameof(PdfViewer);
     private const string pageUrl = DemoRouteConstants.Demos_PdfViewer_Documentation;

BlazorExpress.Bulma.Demo.RCL/Pages/Demos/PdfViewer/PdfViewer_Demo_04_Password_Protected_A.razor

@@ -0,0 +1,3 @@
+<PdfViewer Class="mb-3"
+           Url="@($"/{DemoStringConstants.StaticAssets_Docs_Path}/pdf_password_protected.pdf")"
+           Password="12345" />

BlazorExpress.Bulma.Demo.RCL/Pages/Demos/PdfViewer/PdfViewer_Demo_05_Password_Protected_B_Prompt_For_Password.razor

@@ -0,0 +1,13 @@
+@if (showPdfViewer)
+{
+    <PdfViewer Class="mb-3"
+               Url="@($"/{DemoStringConstants.StaticAssets_Docs_Path}/pdf_password_protected.pdf")" />
+}
+else
+{
+    <Button Class="btn btn-secondary mb-3" @onclick="() => showPdfViewer = true">Load Password Protected PDF (Prompt for Password)</Button>
+}
+
+@code {
+    private bool showPdfViewer = false;
+}

BlazorExpress.Bulma.Demo.RCL/Pages/Docs/PdfViewer/PdfViewer_Doc_01_Documentation.razor

@@ -19,9 +19,9 @@
     <DocxTable TItem="PdfViewer" DocType="DocType.Parameters" />
 </Section>
 
-<Section Class="p-0" Size="HeadingSize.H4" Name="Methods" PageUrl="@pageUrl" Link="methods">
+@* <Section Class="p-0" Size="HeadingSize.H4" Name="Methods" PageUrl="@pageUrl" Link="methods">
     <DocxTable TItem="PdfViewer" DocType="DocType.Methods" />
-</Section>
+</Section> *@
 
 <Section Class="p-0" Size="HeadingSize.H4" Name="Events" PageUrl="@pageUrl" Link="events">
     <DocxTable TItem="PdfViewer" DocType="DocType.Events" />

BlazorExpress.Bulma.Demo.RCL/wwwroot/docs/pdf_password_protected.pdf

@@ -32,7 +32,7 @@ public partial class PdfViewer : BulmaComponentBase
     protected override async Task OnAfterRenderAsync(bool firstRender)
     {
         if (firstRender)
-            await PdfViewerJsInterop.InitializeAsync(objRef!, Id!, scale, rotation, Url!);
+            await PdfViewerJsInterop.InitializeAsync(objRef!, Id!, scale, rotation, Url!, Password!);
 
         await base.OnAfterRenderAsync(firstRender);
     }
@@ -73,6 +73,15 @@ public void DocumentLoaded(PdfViewerModel pdfViewerModel)
             OnDocumentLoaded.InvokeAsync(new PdfViewerEventArgs(pageNumber, pagesCount));
     }
 
+    [JSInvokable]
+    public void DocumentLoadError(string errorMessage)
+    {
+        if (string.IsNullOrEmpty(errorMessage)) return;
+
+        if (OnDocumentLoadError.HasDelegate)
+            OnDocumentLoadError.InvokeAsync(errorMessage);
+    }
+
     [JSInvokable]
     public void SetPdfViewerMetaData(PdfViewerModel pdfViewerModel)
     {
@@ -228,12 +237,24 @@ private async Task ZoomOutAsync()
     /// <summary>
     /// This event fires immediately after the PDF document is loaded.
     /// </summary>
+    [AddedVersion("1.0.0")]
+    [Description("This event fires immediately after the PDF document is loaded.")]
     [Parameter]
     public EventCallback<PdfViewerEventArgs> OnDocumentLoaded { get; set; }
 
+    /// <summary>
+    /// This event fires if there is an error loading the PDF document.
+    /// </summary>
+    [AddedVersion("1.1.0")]
+    [Description("This event fires if there is an error loading the PDF document.")]
+    [Parameter]
+    public EventCallback<string> OnDocumentLoadError { get; set; }
+
     /// <summary>
     /// This event fires immediately after the page is changed.
     /// </summary>
+    [AddedVersion("1.0.0")]
+    [Description("This event fires immediately after the page is changed.")]
     [Parameter]
     public EventCallback<PdfViewerEventArgs> OnPageChanged { get; set; }
 
@@ -243,9 +264,25 @@ private async Task ZoomOutAsync()
     /// <remarks>
     /// Default value is <see cref="Orientation.Portrait" />.
     /// </remarks>
+    [AddedVersion("1.0.0")]
+    [DefaultValue(Orientation.Portrait)]
+    [Description("Gets or sets the preferred orientation for the PDF viewer.")]
     [Parameter]
     public Orientation Orientation { get; set; } = Orientation.Portrait;
 
+    /// <summary>
+    /// Gets or sets the password used for the PDF document if it is password-protected.
+    /// </summary>
+    /// <remarks>
+    /// Default value is <see langword="null"/>.
+    /// </remarks>
+    [AddedVersion("1.1.0")]
+    [DefaultValue(null)]
+    [Description("Gets or sets the password used for the PDF document if it is password-protected.")]
+    [Parameter]
+    [ParameterTypeName("string?")]
+    public string? Password { get; set; }
+
     /// <summary>
     /// Provides JavaScript interop functionality for the PDF viewer.
     /// </summary>
@@ -259,7 +296,11 @@ private async Task ZoomOutAsync()
     /// <remarks>
     /// Default value is null.
     /// </remarks>
+    [AddedVersion("1.0.0")]
+    [DefaultValue(null)]
+    [Description("Gets or sets the URL of the PDF document to be displayed. PDF Viewer component supports base64 string as a URL.")]
     [Parameter]
+    [ParameterTypeName("string?")]
     public string? Url { get; set; }
 
     #endregion

BlazorExpress.Bulma/Components/PdfViewer/PdfViewer.razor.cs

@@ -41,10 +41,10 @@ public async Task GotoPageAsync(object objRef, string elementId, int gotoPageNum
         await module.InvokeVoidAsync("gotoPage", objRef, elementId, gotoPageNum);
     }
 
-    public async Task InitializeAsync(object objRef, string elementId, double scale, double rotation, string url)
+    public async Task InitializeAsync(object objRef, string elementId, double scale, double rotation, string url, string password)
     {
         var module = await moduleTask.Value;
-        await module.InvokeVoidAsync("initialize", objRef, elementId, scale, rotation, url);
+        await module.InvokeVoidAsync("initialize", objRef, elementId, scale, rotation, url, password);
     }
 
     public async Task LastPageAsync(object objRef, string elementId)

BlazorExpress.Bulma/Components/PdfViewer/PdfViewerJsInterop.cs

@@ -194,17 +194,57 @@ pageRotateCwButton.disabled = this.pagesCount === 0;
 pageRotateCcwButton.disabled = this.pagesCount === 0;
 */
 
-export function initialize(dotNetHelper, elementId, scale, rotation, url) {
+export function initialize(dotNetHelper, elementId, scale, rotation, url, password = null) {
     const pdf = new Pdf(elementId);
     pdf.scale = scale;
     pdf.rotation = rotation;
 
-    pdfJS.getDocument(url).promise.then(function (doc) {
-        pdf.pdfDoc = doc;
-        pdf.pagesCount = doc.numPages;
-        renderPage(pdf, pdf.pageNum);
-        dotNetHelper.invokeMethodAsync('DocumentLoaded', { pagesCount: pdf.pagesCount, pageNumber: pdf.pageNum });
-    });
+    // prepare loading options (optional password allowed)
+    const options = { url };
+    if (password) {
+        options.password = password; // pre-supply if user already has it
+    }
+
+    // begin loading document
+    const loadingTask = pdfJS.getDocument(options);
+
+    // handle password only when required (optional password support)
+    loadingTask.onPassword = function (updatePassword, reason) {
+        if (reason === pdfJS.PasswordResponses.NEED_PASSWORD) {
+            // only prompt if PDF actually requires password
+            const password = prompt("This PDF is password protected. Enter password:");
+            updatePassword(password);
+        } else if (reason === pdfJS.PasswordResponses.INCORRECT_PASSWORD) {
+            const password = prompt("Incorrect password. Please try again:");
+            updatePassword(password);
+        }
+    };
+
+    // handle the promise
+    loadingTask
+        .promise
+        .then(function (doc) {
+            pdf.pdfDoc = doc;
+            pdf.pagesCount = doc.numPages;
+            renderPage(pdf, pdf.pageNum);
+
+            // notify .NET side that document is loaded
+            dotNetHelper.invokeMethodAsync('DocumentLoaded', {
+                pagesCount: pdf.pagesCount,
+                pageNumber: pdf.pageNum
+            });
+        })
+        .catch(function (error) {
+            console.error("PDF loading error:", error);
+
+            // handle password exceptions specifically
+            if (error.name === "PasswordException") {
+                console.error("Password required but not provided");
+            }
+
+            // notify .NET side that document loading failed
+            dotNetHelper.invokeMethodAsync('DocumentLoadError', error.message);
+        });
 }
 
 function isDomSupported() {