@operato/shell 10.11.0 → 10.15.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@operato/shell",
   "description": "WebApplication architecturing shell following open-wc recommendations",
   "author": "heartyoh",
-  "version": "10.11.0",
+  "version": "10.15.0",
   "type": "module",
   "main": "dist/src/index.js",
   "module": "dist/src/index.js",
@@ -60,10 +60,10 @@
   },
   "dependencies": {
     "@material/web": "^2.0.0",
-    "@operato/graphql": "^10.11.0",
-    "@operato/popup": "^10.11.0",
-    "@operato/styles": "^10.10.0",
-    "@operato/utils": "^10.11.0",
+    "@operato/graphql": "^10.15.0",
+    "@operato/popup": "^10.15.0",
+    "@operato/styles": "^10.15.0",
+    "@operato/utils": "^10.15.0",
     "@webcomponents/scoped-custom-element-registry": "^0.0.9",
     "lit": "^3.1.2",
     "lodash-es": "^4.17.21",
@@ -102,5 +102,5 @@
       "prettier --write"
     ]
   },
-  "gitHead": "2a99beffd64627b7e2d8cf0dca1422c77079af7c"
+  "gitHead": "62ac2a23866e7ea579786c4433ef356888dfded8"
 }

package/test/fixtures/guarded-define.ts

@@ -0,0 +1,11 @@
+/**
+ * A hand-written component that checks the registry before defining.
+ *
+ * Nothing throws, the module resolves, and somebody else's constructor stays registered. Only the
+ * identity comparison sees this.
+ */
+export class Guarded extends HTMLElement {}
+
+if (!customElements.get('probe-guarded-clash')) {
+  customElements.define('probe-guarded-clash', Guarded)
+}

package/test/fixtures/no-registration.ts

@@ -0,0 +1,2 @@
+/** Loads fine and registers nothing — the shape a stale hand copy produces. */
+export class NeverRegistered extends HTMLElement {}

package/test/fixtures/registers.ts

@@ -0,0 +1,11 @@
+/**
+ * A module that registers its element while being evaluated, the way lit's decorator does.
+ *
+ * A real module rather than a thunk that throws, because *when* the define runs is the whole
+ * point: it runs during evaluation, so a clash takes the module down with it and the caller sees a
+ * rejected import rather than a bad return value. A synthetic throw would skip the module loader
+ * and prove nothing about that.
+ */
+export class Registers extends HTMLElement {}
+
+customElements.define('probe-registers', Registers)

package/test/fixtures/unguarded-define.ts

@@ -0,0 +1,9 @@
+/**
+ * The losing half of a clash: defines unconditionally, exactly as `@customElement` compiles to.
+ *
+ * The test registers this tag first, so evaluating this module throws NotSupportedError out of the
+ * loader — the shape a real duplicate arrives in.
+ */
+export class Unguarded extends HTMLElement {}
+
+customElements.define('probe-unguarded-clash', Unguarded)

package/test/require-custom-element.test.ts

@@ -0,0 +1,287 @@
+import { expect } from '@open-wc/testing'
+
+import { forgetRegisteredElements, requireCustomElement } from '../src/require-custom-element.js'
+
+/**
+ * Every case here is a planted defect.
+ *
+ * A guard that has never been made to fail is indistinguishable from a guard that is dead: both
+ * report nothing. So each branch gets a situation built to trip it, and the assertion is that the
+ * guard names *that* branch — not merely that it complained.
+ *
+ * The two clash cases matter most. A clash is the accident this repo has actually had, it is the
+ * rarest branch to reach, and it arrives by two different routes that a single test would leave
+ * half covered.
+ *
+ * ── Why the fixtures are real modules ───────────────────────────────────────
+ * The failing paths import files under `fixtures/` rather than calling a thunk that throws. A
+ * module's define runs while the module is being evaluated, and that is exactly what decides
+ * whether the caller sees a rejection or a bad return value; a synthetic throw skips the loader and
+ * would agree with the guard for the wrong reason.
+ *
+ * These tests run on the platform's own loader. Webpack's is a second question, answered by
+ * reading its shipped runtime rather than here — the header of the module under test carries that
+ * measurement, including why a retried clash comes back as an empty module.
+ *
+ * Fixture tags are fixed strings and a module evaluates once per page, so each fixture belongs to
+ * exactly one test.
+ */
+
+/** Unique per test, so registrations never leak between them — the registry cannot be undone. */
+let counter = 0
+function freshTag(): string {
+  counter += 1
+  return `require-probe-${counter}-${Math.random().toString(36).slice(2, 8)}`
+}
+
+describe('requireCustomElement', () => {
+  beforeEach(() => {
+    /* The table of who registered what is page-wide; tests must not inherit each other's winners. */
+    forgetRegisteredElements()
+  })
+
+  it('passes when the specifier registers the element and the registered class is that one', async () => {
+    const check = await requireCustomElement({
+      name: 'probe-registers',
+      load: () => import('./fixtures/registers.js') as unknown as Promise<Record<string, unknown>>,
+      specifier: './fixtures/registers.js',
+      exportName: 'Registers'
+    })
+
+    expect(check.ok).to.be.true
+  })
+
+  it('reports load-failed when the import rejects', async () => {
+    /*
+     * Held in a variable so the compiler leaves it alone: the point is a specifier that resolves at
+     * build time and fails in the browser, which is the shape this repo's import mistakes take.
+     */
+    const missing = './fixtures/not-a-file.js'
+
+    const check = await requireCustomElement({
+      name: freshTag(),
+      load: () => import(missing) as unknown as Promise<Record<string, unknown>>,
+      specifier: missing,
+      exportName: 'Element'
+    })
+
+    expect(check.ok).to.be.false
+    if (check.ok) return
+    expect(check.reason).to.equal('load-failed')
+    /* The specifier is the thing to change, so it has to appear in the line that says so. */
+    expect(check.detail).to.contain('./fixtures/not-a-file.js')
+  })
+
+  it('reports missing-from-module when the import resolves without registering', async () => {
+    const check = await requireCustomElement({
+      name: freshTag(),
+      load: () => import('./fixtures/no-registration.js') as unknown as Promise<Record<string, unknown>>,
+      specifier: './fixtures/no-registration.js',
+      exportName: 'NeverRegistered'
+    })
+
+    expect(check.ok).to.be.false
+    if (check.ok) return
+    expect(check.reason).to.equal('missing-from-module')
+  })
+
+  it('reports duplicate when an unguarded define clashes and takes its module down', async () => {
+    /* Another copy got there first. */
+    class Theirs extends HTMLElement {}
+    customElements.define('probe-unguarded-clash', Theirs)
+
+    const check = await requireCustomElement({
+      name: 'probe-unguarded-clash',
+      load: () => import('./fixtures/unguarded-define.js') as unknown as Promise<Record<string, unknown>>,
+      specifier: './fixtures/unguarded-define.js',
+      exportName: 'Unguarded'
+    })
+
+    expect(check.ok).to.be.false
+    if (check.ok) return
+    /*
+     * The import rejects here, so without the NotSupportedError branch this reads as a wrong path —
+     * and the fix for a wrong path (change the specifier) is the opposite of the fix for this
+     * (delete one of the two copies).
+     */
+    expect(check.reason).to.equal('duplicate')
+  })
+
+  it('reports duplicate when the module guards its own define and stays quiet', async () => {
+    class Theirs extends HTMLElement {}
+    customElements.define('probe-guarded-clash', Theirs)
+
+    const check = await requireCustomElement({
+      name: 'probe-guarded-clash',
+      load: () => import('./fixtures/guarded-define.js') as unknown as Promise<Record<string, unknown>>,
+      specifier: './fixtures/guarded-define.js',
+      exportName: 'Guarded'
+    })
+
+    expect(check.ok).to.be.false
+    if (check.ok) return
+    /* Nothing threw and the registry answers truthy, so only the constructor identity sees this. */
+    expect(check.reason).to.equal('duplicate')
+    expect(customElements.get('probe-guarded-clash')).to.equal(Theirs)
+  })
+
+  it('names both specifiers in a clash once one of them has passed a check', async () => {
+    const tag = freshTag()
+
+    class Mine extends HTMLElement {}
+    const winner = '@scope/pkg/dist-client/index.js'
+    const loser = '@scope/pkg/client'
+
+    await requireCustomElement({
+      name: tag,
+      load: async () => {
+        customElements.define(tag, Mine)
+        return { Element: Mine }
+      },
+      specifier: winner,
+      exportName: 'Element'
+    })
+
+    const check = await requireCustomElement({
+      name: tag,
+      load: async () => ({ Element: class extends HTMLElement {} }),
+      specifier: loser,
+      exportName: 'Element'
+    })
+
+    expect(check.ok).to.be.false
+    if (check.ok) return
+    /*
+     * A clash is the one failure whose fix lives in a file the complaining host does not name.
+     * Without the winner the reader starts at grep; with it, the line is the whole answer.
+     */
+    expect(check.detail).to.contain(winner)
+    expect(check.detail).to.contain(loser)
+  })
+
+  it('calls a retried clash a clash, not a wrong export name', async () => {
+    const tag = freshTag()
+
+    class Mine extends HTMLElement {}
+    await requireCustomElement({
+      name: tag,
+      load: async () => {
+        customElements.define(tag, Mine)
+        return { Element: Mine }
+      },
+      specifier: '@scope/pkg/dist-client/index.js',
+      exportName: 'Element'
+    })
+
+    /*
+     * Models what webpack does, measured off its shipped runtime: a module that threw stays cached
+     * with empty exports and no error recorded, so importing it a second time resolves with `{}`.
+     * The tag is registered by someone, and the export is missing — which is also what a caller
+     * with the wrong exportName looks like. Only the record of who registered it separates them,
+     * and sending this reader to fix an exportName would be sending them to the wrong file.
+     */
+    const check = await requireCustomElement({
+      name: tag,
+      load: async () => ({}),
+      specifier: '@scope/pkg/client',
+      exportName: 'Element'
+    })
+
+    expect(check.ok).to.be.false
+    if (check.ok) return
+    expect(check.reason).to.equal('duplicate')
+  })
+
+  it('reports export-not-found when the caller names the wrong export and no one else owns the tag', async () => {
+    const tag = freshTag()
+
+    const check = await requireCustomElement({
+      name: tag,
+      load: async () => {
+        customElements.define(tag, class extends HTMLElement {})
+        return { Element: class extends HTMLElement {} }
+      },
+      specifier: '@scope/pkg/dist-client/index.js',
+      exportName: 'WrongName'
+    })
+
+    expect(check.ok).to.be.false
+    if (check.ok) return
+    /*
+     * The element registered correctly here. Comparing against an absent export would have made a
+     * healthy load look like a clash and sent someone hunting for a second copy that is not there.
+     */
+    expect(check.reason).to.equal('export-not-found')
+  })
+
+  it('falls back to no-answer only when the import never settles', async () => {
+    const check = await requireCustomElement({
+      name: freshTag(),
+      load: () => new Promise<Record<string, unknown>>(() => {}),
+      specifier: '@scope/pkg/dist-client/index.js',
+      exportName: 'Element',
+      timeout: 50
+    })
+
+    expect(check.ok).to.be.false
+    if (check.ok) return
+    expect(check.reason).to.equal('no-answer')
+  })
+
+  it('does not time out a slow import that does arrive', async () => {
+    const tag = freshTag()
+
+    const check = await requireCustomElement({
+      name: tag,
+      load: async () => {
+        await new Promise(resolve => setTimeout(resolve, 60))
+        class Element extends HTMLElement {}
+        customElements.define(tag, Element)
+        return { Element }
+      },
+      specifier: '@scope/pkg/dist-client/index.js',
+      exportName: 'Element',
+      timeout: 300
+    })
+
+    /*
+     * Slow is not wrong. The backstop exists for an import that never settles, and a load that is
+     * merely late must pass — otherwise the guard answers a question about the network with a
+     * sentence about the code.
+     */
+    expect(check.ok).to.be.true
+  })
+
+  it('gives the viewer a different line for a clash than for a part that did not load', async () => {
+    const missingTag = freshTag()
+    const clashTag = freshTag()
+
+    class Theirs extends HTMLElement {}
+    customElements.define(clashTag, Theirs)
+
+    const missing = await requireCustomElement({
+      name: missingTag,
+      load: async () => ({ Element: class extends HTMLElement {} }),
+      specifier: '@scope/pkg/dist-client/index.js',
+      exportName: 'Element'
+    })
+    const clash = await requireCustomElement({
+      name: clashTag,
+      load: async () => ({ Element: class extends HTMLElement {} }),
+      specifier: '@scope/pkg/dist-client/index.js',
+      exportName: 'Element'
+    })
+
+    expect(missing.ok).to.be.false
+    expect(clash.ok).to.be.false
+    if (missing.ok || clash.ok) return
+
+    /*
+     * The wording lives in the guard so the three docks cannot drift apart, and the two situations
+     * have to reach the viewer as different sentences — one is a part that is absent, the other a
+     * part that is present twice.
+     */
+    expect(missing.key).to.not.equal(clash.key)
+    expect(missing.defaultValue).to.not.equal(clash.defaultValue)
+  })
+})