Update snippet documentation and improve UI plugin for disabling categories

Author: bobsingor

.changeset/hidden-items-dependency-rules.md

@@ -0,0 +1,22 @@
+---
+'@embedpdf/plugin-ui': minor
+---
+
+Added `data-hidden-items` attribute for efficient CSS dependency rules.
+
+**Problem**: Visibility dependency rules (e.g., hiding overflow buttons when all menu items are hidden) required exponential CSS rules when using category-based logic, causing stylesheet bloat.
+
+**Solution**:
+
+- Added `hiddenItems` state that tracks which item IDs are hidden based on disabled categories
+- Dependency rules now use `data-epdf-hid` attribute to check item IDs directly
+- CSS rules are now O(n) per breakpoint instead of O(m^n)
+
+**New APIs**:
+
+- `getHiddenItems()` - returns array of hidden item IDs
+- `onCategoryChanged` event now includes `hiddenItems` in payload
+- `extractItemCategories(schema)` - extracts item→categories mapping
+- `computeHiddenItems(itemCategories, disabledCategories)` - computes hidden items
+
+**Breaking Changes**: None - existing `disabledCategories` API unchanged

.changeset/snippet-disabled-categories-and-hierarchical-categories.md

@@ -0,0 +1,65 @@
+---
+'@embedpdf/snippet': minor
+---
+
+Added global `disabledCategories` config and hierarchical categories for fine-grained feature control.
+
+**Global `disabledCategories` Configuration**
+
+Added `disabledCategories` to the root `PDFViewerConfig` that applies to both UI and Commands plugins:
+
+```typescript
+const config: PDFViewerConfig = {
+  src: 'document.pdf',
+  // Disable all annotation and redaction features globally
+  disabledCategories: ['annotation', 'redaction'],
+};
+```
+
+Plugin-specific settings can override the global setting:
+
+```typescript
+const config: PDFViewerConfig = {
+  disabledCategories: ['annotation'], // Global default
+  ui: {
+    disabledCategories: ['redaction'], // Overrides for UI only
+  },
+  commands: {
+    disabledCategories: [], // Re-enables all for commands
+  },
+};
+```
+
+**Hierarchical Categories**
+
+All commands and UI schema items now have hierarchical categories for granular control:
+
+- `annotation` - all annotation features
+  - `annotation-markup` - highlight, underline, strikeout, squiggly
+    - `annotation-highlight`, `annotation-underline`, etc.
+  - `annotation-shape` - rectangle, circle, line, arrow, polygon, polyline
+    - `annotation-rectangle`, `annotation-circle`, etc.
+  - `annotation-ink`, `annotation-text`, `annotation-stamp`
+- `redaction` - all redaction features
+  - `redaction-text`, `redaction-area`, `redaction-apply`, `redaction-clear`
+- `zoom` - all zoom features
+  - `zoom-in`, `zoom-out`, `zoom-fit-page`, `zoom-fit-width`, `zoom-marquee`
+  - `zoom-level` - all zoom level presets
+- `document` - document operations
+  - `document-open`, `document-close`, `document-print`, `document-export`, `document-fullscreen`
+- `panel` - sidebar panels
+  - `panel-sidebar`, `panel-search`, `panel-comment`, `panel-annotation-style`
+- `page` - page settings
+  - `spread`, `scroll`, `rotate`
+- `history` - undo/redo
+  - `history-undo`, `history-redo`
+- `mode` - viewer modes
+  - `mode-view`, `mode-annotate`, `mode-shapes`, `mode-redact`
+- `tools` - tool buttons
+  - `pan`, `pointer`, `capture`
+
+Example: Disable only print functionality while keeping export:
+
+```typescript
+disabledCategories: ['document-print'];
+```

packages/plugin-ui/src/lib/actions.ts

@@ -23,6 +23,7 @@ export const CLOSE_ALL_MENUS = 'UI/CLOSE_ALL_MENUS';
 
 // Category actions
 export const SET_DISABLED_CATEGORIES = 'UI/SET_DISABLED_CATEGORIES';
+export const SET_HIDDEN_ITEMS = 'UI/SET_HIDDEN_ITEMS';
 
 export interface InitUIStateAction extends Action {
   type: typeof INIT_UI_STATE;
@@ -102,6 +103,11 @@ export interface SetDisabledCategoriesAction extends Action {
   payload: { categories: string[] };
 }
 
+export interface SetHiddenItemsAction extends Action {
+  type: typeof SET_HIDDEN_ITEMS;
+  payload: { hiddenItems: string[] };
+}
+
 export type UIAction =
   | InitUIStateAction
   | CleanupUIStateAction
@@ -116,7 +122,8 @@ export type UIAction =
   | OpenMenuAction
   | CloseMenuAction
   | CloseAllMenusAction
-  | SetDisabledCategoriesAction;
+  | SetDisabledCategoriesAction
+  | SetHiddenItemsAction;
 
 // Action creators
 export const initUIState = (documentId: string, schema: UISchema): InitUIStateAction => ({
@@ -213,3 +220,8 @@ export const setDisabledCategories = (categories: string[]): SetDisabledCategori
   type: SET_DISABLED_CATEGORIES,
   payload: { categories },
 });
+
+export const setHiddenItems = (hiddenItems: string[]): SetHiddenItemsAction => ({
+  type: SET_HIDDEN_ITEMS,
+  payload: { hiddenItems },
+});

packages/plugin-ui/src/lib/reducer.ts

@@ -15,6 +15,7 @@ import {
   CLOSE_MENU,
   CLOSE_ALL_MENUS,
   SET_DISABLED_CATEGORIES,
+  SET_HIDDEN_ITEMS,
 } from './actions';
 
 export const initialDocumentState: UIDocumentState = {
@@ -28,6 +29,7 @@ export const initialDocumentState: UIDocumentState = {
 export const initialState: UIState = {
   documents: {},
   disabledCategories: [],
+  hiddenItems: [],
 };
 
 export const uiReducer = (state = initialState, action: UIAction): UIState => {
@@ -332,6 +334,13 @@ export const uiReducer = (state = initialState, action: UIAction): UIState => {
       };
     }
 
+    case SET_HIDDEN_ITEMS: {
+      return {
+        ...state,
+        hiddenItems: action.payload.hiddenItems,
+      };
+    }
+
     default:
       return state;
   }

packages/plugin-ui/src/lib/types.ts

@@ -21,6 +21,9 @@ export interface UIState {
 
   /** Globally disabled categories */
   disabledCategories: string[];
+
+  /** Item IDs that are hidden (computed from disabled categories) */
+  hiddenItems: string[];
 }
 
 /**
@@ -239,6 +242,7 @@ export interface UICapability {
   setDisabledCategories(categories: string[]): void;
   getDisabledCategories(): string[];
   isCategoryDisabled(category: string): boolean;
+  getHiddenItems(): string[];
 
   // Global events
   onToolbarChanged: EventHook<{
@@ -255,5 +259,5 @@ export interface UICapability {
   }>;
   onModalChanged: EventHook<{ documentId: string; modalId: string | null; isOpen: boolean }>;
   onMenuChanged: EventHook<{ documentId: string; menuId: string; isOpen: boolean }>;
-  onCategoryChanged: EventHook<{ disabledCategories: string[] }>;
+  onCategoryChanged: EventHook<{ disabledCategories: string[]; hiddenItems: string[] }>;
 }

packages/plugin-ui/src/lib/ui-plugin.ts

@@ -41,16 +41,25 @@ import {
   closeMenu,
   closeAllMenus,
   setDisabledCategories,
+  setHiddenItems,
 } from './actions';
 import { mergeUISchema } from './utils/schema-merger';
-import { generateUIStylesheet, StylesheetConfig } from './utils';
+import {
+  generateUIStylesheet,
+  extractItemCategories,
+  computeHiddenItems,
+  StylesheetConfig,
+} from './utils';
 
 export class UIPlugin extends BasePlugin<UIPluginConfig, UICapability, UIState, UIAction> {
   static readonly id = 'ui' as const;
 
   private schema: UISchema;
   private stylesheetConfig: StylesheetConfig;
 
+  // Item categories mapping for computing hidden items
+  private itemCategories: Map<string, string[]>;
+
   // Stylesheet caching with locale awareness
   private cachedStylesheet: string | null = null;
   private cachedLocale: string | null = null;
@@ -60,7 +69,10 @@ export class UIPlugin extends BasePlugin<UIPluginConfig, UICapability, UIState,
   private i18nCleanup: (() => void) | null = null;
 
   // Events
-  private readonly categoryChanged$ = createBehaviorEmitter<{ disabledCategories: string[] }>();
+  private readonly categoryChanged$ = createBehaviorEmitter<{
+    disabledCategories: string[];
+    hiddenItems: string[];
+  }>();
   private readonly stylesheetInvalidated$ = createEmitter<void>();
 
   private readonly toolbarChanged$ = createScopedEmitter<
@@ -90,9 +102,15 @@ export class UIPlugin extends BasePlugin<UIPluginConfig, UICapability, UIState,
     this.schema = config.schema;
     this.stylesheetConfig = config.stylesheetConfig || {};
 
+    // Extract item categories for computing hidden items
+    this.itemCategories = extractItemCategories(this.schema);
+
     // Initialize disabled categories from config
     if (config.disabledCategories?.length) {
       this.dispatch(setDisabledCategories(config.disabledCategories));
+      // Also compute and dispatch hidden items
+      const hiddenItems = computeHiddenItems(this.itemCategories, config.disabledCategories);
+      this.dispatch(setHiddenItems(hiddenItems));
     }
 
     this.i18n = registry.getPlugin<I18nPlugin>('i18n')?.provides() ?? null;
@@ -206,17 +224,23 @@ export class UIPlugin extends BasePlugin<UIPluginConfig, UICapability, UIState,
     const current = new Set(this.state.disabledCategories);
     if (!current.has(category)) {
       current.add(category);
-      this.dispatch(setDisabledCategories(Array.from(current)));
-      this.categoryChanged$.emit({ disabledCategories: Array.from(current) });
+      const categories = Array.from(current);
+      this.dispatch(setDisabledCategories(categories));
+      const hiddenItems = computeHiddenItems(this.itemCategories, categories);
+      this.dispatch(setHiddenItems(hiddenItems));
+      this.categoryChanged$.emit({ disabledCategories: categories, hiddenItems });
     }
   }
 
   private enableCategoryImpl(category: string): void {
     const current = new Set(this.state.disabledCategories);
     if (current.has(category)) {
       current.delete(category);
-      this.dispatch(setDisabledCategories(Array.from(current)));
-      this.categoryChanged$.emit({ disabledCategories: Array.from(current) });
+      const categories = Array.from(current);
+      this.dispatch(setDisabledCategories(categories));
+      const hiddenItems = computeHiddenItems(this.itemCategories, categories);
+      this.dispatch(setHiddenItems(hiddenItems));
+      this.categoryChanged$.emit({ disabledCategories: categories, hiddenItems });
     }
   }
 
@@ -230,7 +254,10 @@ export class UIPlugin extends BasePlugin<UIPluginConfig, UICapability, UIState,
 
   private setDisabledCategoriesImpl(categories: string[]): void {
     this.dispatch(setDisabledCategories(categories));
-    this.categoryChanged$.emit({ disabledCategories: categories });
+    // Compute and dispatch hidden items based on disabled categories
+    const hiddenItems = computeHiddenItems(this.itemCategories, categories);
+    this.dispatch(setHiddenItems(hiddenItems));
+    this.categoryChanged$.emit({ disabledCategories: categories, hiddenItems });
   }
 
   // ─────────────────────────────────────────────────────────
@@ -268,6 +295,7 @@ export class UIPlugin extends BasePlugin<UIPluginConfig, UICapability, UIState,
       setDisabledCategories: (categories) => this.setDisabledCategoriesImpl(categories),
       getDisabledCategories: () => this.state.disabledCategories,
       isCategoryDisabled: (category) => this.state.disabledCategories.includes(category),
+      getHiddenItems: () => this.state.hiddenItems,
 
       // Events
       onToolbarChanged: this.toolbarChanged$.onGlobal,

packages/plugin-ui/src/lib/utils/consts.ts

@@ -12,6 +12,8 @@ export const UI_ATTRIBUTES = {
   CATEGORIES: 'data-epdf-cat',
   /** Disabled categories list on root element */
   DISABLED_CATEGORIES: 'data-epdf-dis',
+  /** Hidden item IDs (computed from disabled categories) */
+  HIDDEN_ITEMS: 'data-epdf-hid',
 } as const;
 
 /**
@@ -23,4 +25,5 @@ export const UI_SELECTORS = {
   ITEM: (id: string) => `[${UI_ATTRIBUTES.ITEM}="${id}"]`,
   CATEGORIES: (category: string) => `[${UI_ATTRIBUTES.CATEGORIES}~="${category}"]`,
   DISABLED_CATEGORY: (category: string) => `[${UI_ATTRIBUTES.DISABLED_CATEGORIES}~="${category}"]`,
+  HIDDEN_ITEM: (itemId: string) => `[${UI_ATTRIBUTES.HIDDEN_ITEMS}~="${itemId}"]`,
 } as const;