feat(handlers): explain the tagName convention, and take app ids with underscores

Like the files sidebar tabs: how the element gets defined, when the
viewer waits for it, and why the name starts with the app id. App ids
like files_pdfviewer have an underscore, which the custom element spec
allows but the tag name check refused.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: John Molakvoæ <14975046+skjnldsv@users.noreply.github.com>

Author: skjnldsv

README.md

@@ -335,8 +335,11 @@ The full handler shape (see the `IHandler` interface):
 
 Gotchas:
 
-- `tagName` must be lowercase, contain a hyphen, and have no leading, trailing
-  or consecutive hyphens (e.g. `my-app-viewer`). An invalid one throws.
+- `tagName` must be lowercase (letters, digits, `_` and `-`), contain a hyphen,
+  and have no leading, trailing or consecutive hyphens. An invalid one throws.
+  Custom elements share one registry for the whole page, so start it with your
+  app id to avoid clashing with another app's: for the app `your_app`, a good
+  name is `your_app-viewer-handler`.
 - `id` must be unique **across every app on the page**, not just your own:
   it is not namespaced for you. A collision does not throw: the second
   registration is silently dropped with a console warning, so pick something

__tests__/fileActions.spec.ts

@@ -118,6 +118,16 @@ describe('registerHandler validation', () => {
 			.toThrow('Handler tagName must not start or end with a hyphen (-)')
 	})
 
+	it('takes a tagName starting with an app id that has an underscore', () => {
+		expect(() => registerHandler(makeHandler({ id: 'pdf', tagName: 'files_pdfviewer-viewer-handler' })))
+			.not.toThrow()
+	})
+
+	it('throws on a tagName with any other character', () => {
+		expect(() => registerHandler(makeHandler({ tagName: 'oca-viewer.pdf' })))
+			.toThrow('Handler tagName must only contain lowercase letters, numbers, underscores (_) and hyphens (-)')
+	})
+
 	it('throws on a tagName ending with a hyphen', () => {
 		expect(() => registerHandler(makeHandler({ tagName: 'oca-viewer-' })))
 			.toThrow('Handler tagName must not start or end with a hyphen (-)')

lib/handlers.ts

@@ -34,7 +34,19 @@ export interface IHandler {
 	iconSvgInline?: string
 
 	/**
-	 * The custom element tag name to use for this handler.
+	 * The tag name of the custom element that shows the file.
+	 *
+	 * The element must be defined under this name with
+	 * `CustomElementRegistry.define()`, either when the handler is registered
+	 * or within the `onInit` callback (preferred, as it keeps the view out of
+	 * the script that runs on every page). With `onInit`, the viewer waits for
+	 * the element to be defined (`customElements.whenDefined()`) before
+	 * rendering it.
+	 *
+	 * Custom elements share one registry for the whole page, so to avoid name
+	 * clashes the name has to start with your app id (e.g. `your_app`). In
+	 * addition to the custom element naming rules (lowercase, with a hyphen),
+	 * a good name would be `your_app-viewer-handler`.
 	 */
 	tagName: string
 
@@ -344,7 +356,7 @@ function validateCustomElementName(tagName: string): void {
 	if (tagName.startsWith('-') || tagName.endsWith('-')) {
 		throw new Error('Handler tagName must not start or end with a hyphen (-)')
 	}
-	if (!/^[a-z][a-z0-9-]*$/.test(tagName)) {
-		throw new Error('Handler tagName must only contain lowercase letters, numbers, and hyphens (-)')
+	if (!/^[a-z][a-z0-9_-]*$/.test(tagName)) {
+		throw new Error('Handler tagName must only contain lowercase letters, numbers, underscores (_) and hyphens (-)')
 	}
 }