Merge pull request #663 from embedpdf/feature/category-based-hiding-overlays

Enable category-based hiding for overlays

Author: bobsingor

.changeset/hide-unlock-owner-overlay.md

@@ -0,0 +1,5 @@
+---
+"@embedpdf/snippet": patch
+---
+
+Allow hiding the UnlockOwnerOverlay (the read-only notice shown on encrypted, permission-restricted PDFs) via `disabledCategories`. The overlay renderer now emits the `data-epdf-cat` attribute, and the `unlock-owner-overlay` overlay carries the new `security` / `security-unlock-overlay` categories, so viewer-only integrations can remove it with `disabledCategories: ['security-unlock-overlay']` (or the parent `security`).

.changeset/overlay-category-support.md

@@ -0,0 +1,5 @@
+---
+"@embedpdf/plugin-ui": patch
+---
+
+Overlays now participate in the category visibility system. The schema analyzer collects overlay `categories` (and `visibilityDependsOn`), so category visibility CSS is generated for them and they can be hidden via `disabledCategories` like any other UI item.

packages/plugin-ui/src/lib/utils/stylesheet-generator.ts

@@ -226,6 +226,18 @@ function analyzeSchema(schema: UISchema, locale?: string): SchemaAnalysis {
     );
   }
 
+  // Analyze overlays
+  for (const [overlayId, overlay] of Object.entries(schema.overlays || {})) {
+    collectCategoriesAndDependency(
+      overlayId,
+      overlay.categories,
+      overlay.visibilityDependsOn,
+      categories,
+      itemCategories,
+      dependencies,
+    );
+  }
+
   return { categories, itemCategories, dependencies, menuBreakpoints, responsiveItems };
 }
 

viewers/snippet/src/config/commands.ts

@@ -487,7 +487,7 @@ export const commands: Record<string, Command<State>> = {
     id: 'document:protect',
     labelKey: 'document.protect',
     icon: 'lock',
-    categories: ['document', 'document-protect'],
+    categories: ['document', 'document-protect', 'security'],
     action: ({ registry, documentId }) => {
       const ui = registry.getPlugin<UIPlugin>('ui')?.provides();
       if (!ui) return;

viewers/snippet/src/config/ui-schema.ts

@@ -1306,7 +1306,7 @@ export const viewerUISchema: UISchema = {
           type: 'command',
           id: 'document:protect',
           commandId: 'document:protect',
-          categories: ['document', 'document-protect'],
+          categories: ['document', 'document-protect', 'security'],
         },
         {
           type: 'command',
@@ -1750,6 +1750,7 @@ export const viewerUISchema: UISchema = {
         type: 'component',
         componentId: 'unlock-owner-overlay',
       },
+      categories: ['security', 'security-unlock-overlay'],
       defaultEnabled: true,
     },
   },

viewers/snippet/src/ui/schema-overlay.tsx

@@ -1,5 +1,5 @@
 import { h } from 'preact';
-import { OverlaySchema, OverlayAnchor } from '@embedpdf/plugin-ui';
+import { OverlaySchema, OverlayAnchor, UI_ATTRIBUTES } from '@embedpdf/plugin-ui';
 import { useItemRenderer } from '@embedpdf/plugin-ui/preact';
 
 export interface OverlayRendererProps {
@@ -59,11 +59,17 @@ export function SchemaOverlay({ schema, documentId, className }: OverlayRenderer
   const anchorClasses = getAnchorClasses(position.anchor);
   const offsetStyles = getOffsetStyles(position.offset);
 
+  const categoryAttr = schema.categories?.length
+    ? { [UI_ATTRIBUTES.CATEGORIES]: schema.categories.join(' ') }
+    : {};
+
   return (
     <div
       className={`z-3 absolute ${anchorClasses} ${className || ''}`}
       style={offsetStyles}
       data-overlay-id={schema.id}
+      {...{ [UI_ATTRIBUTES.ITEM]: schema.id }}
+      {...categoryAttr}
     >
       {renderCustomComponent(content.componentId, documentId)}
     </div>

website/src/content/docs/react/viewer/customizing-ui.mdx

@@ -62,6 +62,7 @@ Categories are hierarchical—disabling a parent category (e.g., `annotation`) d
 | **Selection** | `selection`, `selection-copy` |
 | **History** | `history`, `history-undo`, `history-redo` |
 | **Insert** | `insert`, `insert-rubber-stamp`, `insert-signature`, `insert-image` |
+| **Security** | `security`, `security-unlock-overlay` |
 
 ## Advanced Customization
 

website/src/content/docs/react/viewer/security.mdx

@@ -74,6 +74,28 @@ The UI automatically adapts to these effective permissions. For example:
 - If `copyContents` is denied, text selection is disabled on the canvas.
 - If `modifyAnnotations` is denied, annotation tools are disabled.
 
+## Hiding the read-only notice
+
+When a document is encrypted **and** has restricted permissions, the viewer shows a small dismissible overlay informing the user that the document is protected (with a "View permissions" link). This is helpful in a full editor, but for a viewer-only integration you may want to remove it entirely.
+
+The overlay is part of the UI category system, so you can hide it with `disabledCategories`:
+
+```tsx
+<PDFViewer
+  config={{
+    src: '/document.pdf',
+    // Remove only the read-only notice overlay...
+    disabledCategories: ['security-unlock-overlay'],
+    // ...or remove all security UI with the parent category:
+    // disabledCategories: ['security'],
+  }}
+/>
+```
+
+<Callout>
+  This only hides the notice from the UI. It does not change or bypass the document's permissions. See [Customizing the UI](./customizing-ui#disabling-features) for the full list of categories.
+</Callout>
+
 ## Interactive Example
 
 Switch between the tabs to see how different permission configurations affect the viewer. Observe how the **Print** button and **Text Selection** behave in each mode.

website/src/content/docs/snippet/customizing-ui.mdx

@@ -56,6 +56,7 @@ Categories are hierarchical—disabling a parent category (e.g., `annotation`) d
 | **Selection** | `selection`, `selection-copy` |
 | **History** | `history`, `history-undo`, `history-redo` |
 | **Insert** | `insert`, `insert-rubber-stamp`, `insert-signature`, `insert-image` |
+| **Security** | `security`, `security-unlock-overlay` |
 
 ## Quick Start: Replacing a Toolbar Button
 

website/src/content/docs/snippet/security.mdx

@@ -73,6 +73,27 @@ The UI automatically adapts to these effective permissions. For example:
 - If `copyContents` is denied, text selection is disabled on the canvas.
 - If `modifyAnnotations` is denied, annotation tools are disabled.
 
+## Hiding the read-only notice
+
+When a document is encrypted **and** has restricted permissions, the snippet shows a small dismissible overlay informing the user that the document is protected (with a "View permissions" link). This is helpful in a full editor, but for a viewer-only integration you may want to remove it entirely.
+
+The overlay is part of the UI category system, so you can hide it with `disabledCategories`:
+
+```js
+EmbedPDF.init({
+  target: document.getElementById('pdf-viewer'),
+  src: 'https://example.com/document.pdf',
+  // Remove only the read-only notice overlay...
+  disabledCategories: ['security-unlock-overlay'],
+  // ...or remove all security UI with the parent category:
+  // disabledCategories: ['security'],
+});
+```
+
+<Callout>
+  This only hides the notice from the UI. It does not change or bypass the document's permissions. See [Customizing the UI](./customizing-ui#disabling-features) for the full list of categories.
+</Callout>
+
 ## Interactive Example
 
 Switch between the tabs to see how different permission configurations affect the viewer. Observe how the **Print** button and **Text Selection** behave in each mode.