@internetarchive/elements 0.4.0 → 0.4.1

package/dist/src/util/custom-element.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Allow for custom element classes with private constructors.
+ */
+type CustomElementClass = Omit<typeof HTMLElement, 'new'>;
+/**
+ * Class decorator factory that registers the decorated class as a custom
+ * element, unless something has already claimed the tag name.
+ *
+ * Each element subpath is served to non-bundler consumers as a self-contained
+ * bundle, so a component several elements share, such as
+ * `ia-status-indicator`, is built into every entry point that imports it. A
+ * page pulling in two of those subpaths therefore evaluates two copies of the
+ * shared component and registers the same tag twice. `customElements.define`
+ * throws on the second attempt, and because that happens while the module is
+ * still evaluating it takes down the rest of the bundle with it, so the
+ * element the page actually asked for never registers.
+ *
+ * Skipping a duplicate keeps the first copy registered and lets the rest of
+ * the module finish. The copies are interchangeable: they are built from the
+ * same source, and nothing narrows a shared element by class identity.
+ *
+ * A skip is also how a page ends up on an element it did not mean to use:
+ * load two versions of the package together, or let a host page claim one of
+ * these tag names, and whichever registered first is what the page gets,
+ * which looks like the expected element's behaviour going missing. Nothing
+ * here can tell that apart from a matched-version duplicate, since two builds
+ * of the same element differ in nothing observable at this point, so a skip
+ * warns and leaves the reader to tell the cases apart.
+ *
+ * ```ts
+ * @customElement('ia-example')
+ * class IAExample extends LitElement {}
+ * ```
+ *
+ * @param tagName The tag name to register the element under.
+ */
+export declare function customElement(tagName: string): (classOrTarget: CustomElementClass, context?: ClassDecoratorContext<new () => HTMLElement>) => void;
+export {};
+//# sourceMappingURL=custom-element.d.ts.map

package/dist/src/util/custom-element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-element.d.ts","sourceRoot":"","sources":["../../../src/util/custom-element.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,KAAK,kBAAkB,GAAG,IAAI,CAAC,OAAO,WAAW,EAAE,KAAK,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,IAEzC,eAAe,kBAAkB,EACjC,UAAU,qBAAqB,CAAC,UAAU,WAAW,CAAC,KACrD,IAAI,CAgBR"}

package/dist/src/util/custom-element.js

@@ -0,0 +1,50 @@
+/**
+ * Class decorator factory that registers the decorated class as a custom
+ * element, unless something has already claimed the tag name.
+ *
+ * Each element subpath is served to non-bundler consumers as a self-contained
+ * bundle, so a component several elements share, such as
+ * `ia-status-indicator`, is built into every entry point that imports it. A
+ * page pulling in two of those subpaths therefore evaluates two copies of the
+ * shared component and registers the same tag twice. `customElements.define`
+ * throws on the second attempt, and because that happens while the module is
+ * still evaluating it takes down the rest of the bundle with it, so the
+ * element the page actually asked for never registers.
+ *
+ * Skipping a duplicate keeps the first copy registered and lets the rest of
+ * the module finish. The copies are interchangeable: they are built from the
+ * same source, and nothing narrows a shared element by class identity.
+ *
+ * A skip is also how a page ends up on an element it did not mean to use:
+ * load two versions of the package together, or let a host page claim one of
+ * these tag names, and whichever registered first is what the page gets,
+ * which looks like the expected element's behaviour going missing. Nothing
+ * here can tell that apart from a matched-version duplicate, since two builds
+ * of the same element differ in nothing observable at this point, so a skip
+ * warns and leaves the reader to tell the cases apart.
+ *
+ * ```ts
+ * @customElement('ia-example')
+ * class IAExample extends LitElement {}
+ * ```
+ *
+ * @param tagName The tag name to register the element under.
+ */
+export function customElement(tagName) {
+    return (classOrTarget, context) => {
+        const define = () => {
+            if (customElements.get(tagName)) {
+                console.warn(`[elements] <${tagName}> is already registered, so this definition was skipped and whatever registered first stays in use. Harmless when a page loads two element subpaths that share a component. Otherwise look for a second copy of the package, or an unrelated element using the same name.`);
+                return;
+            }
+            customElements.define(tagName, classOrTarget);
+        };
+        // Standard decorators defer registration to an initializer; the legacy
+        // decorators this project compiles with hand over the class directly.
+        if (context)
+            context.addInitializer(define);
+        else
+            define();
+    };
+}
+//# sourceMappingURL=custom-element.js.map

package/dist/src/util/custom-element.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-element.js","sourceRoot":"","sources":["../../../src/util/custom-element.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,OAAO,CACL,aAAiC,EACjC,OAAsD,EAChD,EAAE;QACR,MAAM,MAAM,GAAG,GAAS,EAAE;YACxB,IAAI,cAAc,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;gBAChC,OAAO,CAAC,IAAI,CACV,eAAe,OAAO,2QAA2Q,CAClS,CAAC;gBACF,OAAO;YACT,CAAC;YACD,cAAc,CAAC,MAAM,CAAC,OAAO,EAAE,aAAyC,CAAC,CAAC;QAC5E,CAAC,CAAC;QAEF,uEAAuE;QACvE,sEAAsE;QACtE,IAAI,OAAO;YAAE,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;;YACvC,MAAM,EAAE,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Allow for custom element classes with private constructors.\n */\ntype CustomElementClass = Omit<typeof HTMLElement, 'new'>;\n\n/**\n * Class decorator factory that registers the decorated class as a custom\n * element, unless something has already claimed the tag name.\n *\n * Each element subpath is served to non-bundler consumers as a self-contained\n * bundle, so a component several elements share, such as\n * `ia-status-indicator`, is built into every entry point that imports it. A\n * page pulling in two of those subpaths therefore evaluates two copies of the\n * shared component and registers the same tag twice. `customElements.define`\n * throws on the second attempt, and because that happens while the module is\n * still evaluating it takes down the rest of the bundle with it, so the\n * element the page actually asked for never registers.\n *\n * Skipping a duplicate keeps the first copy registered and lets the rest of\n * the module finish. The copies are interchangeable: they are built from the\n * same source, and nothing narrows a shared element by class identity.\n *\n * A skip is also how a page ends up on an element it did not mean to use:\n * load two versions of the package together, or let a host page claim one of\n * these tag names, and whichever registered first is what the page gets,\n * which looks like the expected element's behaviour going missing. Nothing\n * here can tell that apart from a matched-version duplicate, since two builds\n * of the same element differ in nothing observable at this point, so a skip\n * warns and leaves the reader to tell the cases apart.\n *\n * ```ts\n * @customElement('ia-example')\n * class IAExample extends LitElement {}\n * ```\n *\n * @param tagName The tag name to register the element under.\n */\nexport function customElement(tagName: string) {\n  return (\n    classOrTarget: CustomElementClass,\n    context?: ClassDecoratorContext<new () => HTMLElement>,\n  ): void => {\n    const define = (): void => {\n      if (customElements.get(tagName)) {\n        console.warn(\n          `[elements] <${tagName}> is already registered, so this definition was skipped and whatever registered first stays in use. Harmless when a page loads two element subpaths that share a component. Otherwise look for a second copy of the package, or an unrelated element using the same name.`,\n        );\n        return;\n      }\n      customElements.define(tagName, classOrTarget as CustomElementConstructor);\n    };\n\n    // Standard decorators defer registration to an initializer; the legacy\n    // decorators this project compiles with hand over the class directly.\n    if (context) context.addInitializer(define);\n    else define();\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@internetarchive/elements",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "A web component library from the Internet Archive.",
   "license": "AGPL-3.0-only",
   "types": "./dist/src/elements/index.d.ts",