resolve #8

README.md

@@ -40,19 +40,23 @@ define('say-hi', ({ to }) => {
 - [Contents](#contents)
 - [Installation](#installation)
 - [Usage](#usage)
-  - [Provided Hooks](#provided-hooks)
-    - [onCleanup](#oncleanup)
-    - [onAttribute](#onattribute)
+  - [Common Hooks](#common-hooks)
+    <!-- - [onAttribute](#onattribute)
     - [onProperty](#onproperty)
     - [on](#on)
     - [useDispatch](#usedispatch)
+    - [currentNode](#currentnode) -->
+  - [Lifecycle Hooks](#lifecycle-hooks)
+    <!-- - [onCleanup](#oncleanup)
+    - [onRendered](#onrendered)
     - [onConnected](#onconnected)
     - [onDisconnected](#ondisconnected)
     - [onAttributeChanged](#onattributechanged)
-    - [onPropertyChanged](#onpropertychanged)
-    - [onRendered](#onrendered)
-    - [currentNode](#currentnode)
-    - [ownerDocument](#ownerdocument)
+    - [onPropertyChanged](#onpropertychanged) -->
+  - [Hooks for SSR](#hooks-for-ssr)
+    <!-- - [ownerDocument](#ownerdocument)
+    - [onHydrated](#onhydrated)
+    - [onFirstRender](#onfirstrender) -->
   - [Rules for Hooks](#rules-for-hooks)
   - [Custom Hooks](#custom-hooks)
   - [Server Side Rendering](#server-side-rendering)
@@ -150,14 +154,9 @@ el.setProperty('myProp', { whatever: 'you want' })
 
 <br>
 
-## Provided Hooks
+## Common Hooks
 
-### onCleanup
-```ts
-onCleanup(hook: () => void)
-```
-
-Is called after the element is removed from the document and not added back immediately.
+The following hooks are commonly used by components:
 
 <br>
 
@@ -228,6 +227,30 @@ define('my-el', () => {
 
 </div>
 
+### currentNode
+
+```ts
+currentNode(): HTMLElement | undefined
+```
+
+Returns the current element being rendered, undefined if used out of a component function. Useful for custom hooks who need
+to conduct an operation during rendering (for hooks that operate after rendering, use `.onRendered()`).
+
+<br>
+
+## Lifecycle Hooks
+
+Use the following hooks to tap into life cycle events of custom elements:
+
+<br>
+
+### onCleanup
+```ts
+onCleanup(hook: () => void)
+```
+
+Is called after the element is removed from the document and not added back immediately.
+
 <br>
 
 ### onConnected
@@ -285,22 +308,40 @@ Is called after the returned DOM is attached to the element's [shadow root](http
 
 <br>
 
-### currentNode
 
-```ts
-currentNode(): HTMLElement | undefined
-```
+## Hooks for SSR
 
-Returns the current element being rendered, undefined if used out of a component function. Useful for custom hooks who need
-to conduct an operation during rendering (for hooks that operate after rendering, use `.onRendered()`).
+The following hooks are useful for server side rendering:
+
+<br>
 
 ### ownerDocument
 
 ```ts
 ownerDocument(): Document
 ```
 
-Returns the document that the element is in. Useful for components (and hooks) that want to be operable in environments where there is no global document object (e.g. during SSR).
+Returns the document that the element is in. Useful for components (and hooks) that want to be operable in environments where there is no global document object.
+
+<br>
+
+### onHydrated
+
+```ts
+onHydrated(hook: (node: HTMLElement) => void)
+```
+
+Is called when the element is hydrated on the client.
+
+<br>
+
+### onFirstRender
+
+```ts
+onFirstRender(hook: (node: HTMLElement) => void)
+```
+
+Is called when the element is rendered for the first time (either on the server or on the client).
 
 <br>
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "minicomp",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Minimalistic library for creating Web Components",
   "main": "dist/commonjs/index.js",
   "module": "dist/es/index.js",
@@ -51,7 +51,7 @@
     "jest-environment-jsdom": "^29.3.1",
     "jsdom": "^21.1.0",
     "quel": "^0.3.2",
-    "rehtm": "^0.2.0",
+    "rehtm": "^0.3.2",
     "sleep-promise": "^9.1.0",
     "ts-inference-check": "^0.2.1",
     "ts-jest": "^29.0.3",

src/component.ts

@@ -62,10 +62,11 @@ export function component(
         this._attributeChanged = hooks.onAttributeChanged
         this._propertyChanged = hooks.onPropertyChanged
 
-        // TODO: test this using happy-dom (https://www.npmjs.com/package/happy-dom)
-        /* istanbul ignore if */
+        let hydrated = false
+
         if (isSSRTemplate(node) && this._shouldHydrate) {
           node.hydrateRoot(this._root)
+          hydrated = true
         } else {
           if (typeof node === 'string') {
             this._root.innerHTML = node
@@ -76,7 +77,7 @@ export function component(
           }
         }
 
-        hooks.onRendered && hooks.onRendered(this)
+        hooks.onRendered && hooks.onRendered(this, hydrated)
       }
 
       this._connected && this._connected(this)

src/hooks.ts

@@ -6,7 +6,7 @@ export const ATTRIBUTE_REMOVED = Symbol()
 export type ConnectedHook = (node: HTMLElement) => void
 export type DisconnectedHook = (node: HTMLElement) => void
 export type AdoptedHook = (node: HTMLElement) => void
-export type RenderedHook = (node: HTMLElement) => void
+export type RenderedHook = (node: HTMLElement, hydrated: boolean) => void
 export type AttributeChangedHook = (name: string, value: string | typeof ATTRIBUTE_REMOVED, node: HTMLElement) => void
 export type PropertyChangedHook = (name: string, value: unknown, node: HTMLElement) => void
 export type Hook =

src/index.ts

@@ -6,4 +6,6 @@ export * from './attribute'
 export * from './on'
 export * from './property'
 export * from './dispatch'
+export * from './ssr-hooks'
+
 

src/ssr-hooks.ts

@@ -0,0 +1,19 @@
+import { onRendered } from './hooks'
+
+
+export function onHydrated(hook: (node: HTMLElement) => void) {
+  onRendered((node, hydrated) => {
+    if (hydrated) {
+      hook(node)
+    }
+  })
+}
+
+
+export function onFirstRender(hook: (node: HTMLElement) => void) {
+  onRendered((node, hydrated) => {
+    if (!hydrated) {
+      hook(node)
+    }
+  })
+}

src/test/define.ssr-test.ts

@@ -1,5 +1,4 @@
-jest.mock('htm/mini', () => require('htm/mini/index.umd.js'))
-
+import './polyfill'
 
 import { JSDOM } from 'jsdom'
 import { using, define, definable } from '../define'

src/test/define.test.ts

@@ -1,8 +1,4 @@
-jest.mock('htm/mini', () => require('htm/mini/index.umd.js'))
-
-import { TextEncoder, TextDecoder } from 'util'
-global.TextEncoder = TextEncoder
-global.TextDecoder = TextDecoder as any
+import './polyfill'
 
 import { JSDOM } from 'jsdom'
 import { template } from 'rehtm'

src/test/exports.test.ts

@@ -4,7 +4,7 @@ import {
   onPropertyChanged, currentNode, hooksMeta, ownerDocument,
   ATTRIBUTE_REMOVED, onAttribute, onProperty, onCleanup, on,
   component, FunctionalComponent, ClassBasedComponent,
-  useDispatch,
+  useDispatch, onHydrated, onFirstRender,
 } from '../index'
 
 
@@ -29,6 +29,8 @@ test('stuff are exported properly.', () => {
   expect(onCleanup).toBeDefined()
   expect(on).toBeDefined()
   expect(useDispatch).toBeDefined()
+  expect(onHydrated).toBeDefined()
+  expect(onFirstRender).toBeDefined()
 
   expect(component).toBeDefined()
   expect(<FunctionalComponent>{}).toBeDefined()

src/test/hooks/on-first-render.test.ts

@@ -0,0 +1,44 @@
+import { polyfillDSD } from '../polyfill'
+
+import { JSDOM } from 'jsdom'
+import { re } from 'rehtm'
+
+import { using }  from '../../define'
+import { onFirstRender } from '../../ssr-hooks'
+
+
+describe(onFirstRender, () => {
+  test('is not called when hydrated.', () => {
+    const cb = jest.fn()
+
+    const window = new JSDOM('<ofr-1><template shadowrootmode="open"><div>Hellow</div></template></ofr-1>').window as any
+    polyfillDSD(window.document)
+
+    const { template } = re(window.document)
+
+    using({ window }).define('ofr-1', () => {
+      onFirstRender(cb)
+
+      return template`<div>Hi!</div>`
+    })
+
+    expect(cb).not.toHaveBeenCalled()
+  })
+
+  test('is called when not hydrated.', () => {
+    const cb = jest.fn()
+
+    const window = new JSDOM('<ofr-2></ofr-2>').window as any
+    polyfillDSD(window.document)
+
+    const { template } = re(window.document)
+
+    using({ window }).define('ofr-2', () => {
+      onFirstRender(cb)
+
+      return template`<div>Hi!</div>`
+    })
+
+    expect(cb).toHaveBeenCalledWith(window.document.querySelector('ofr-2'))
+  })
+})

src/test/hooks/on-hydrated.test.ts

@@ -0,0 +1,44 @@
+import { polyfillDSD } from '../polyfill'
+
+import { JSDOM } from 'jsdom'
+import { re } from 'rehtm'
+
+import { using }  from '../../define'
+import { onHydrated } from '../../ssr-hooks'
+
+
+describe(onHydrated, () => {
+  test('is called when hydrated.', () => {
+    const cb = jest.fn()
+
+    const window = new JSDOM('<oh-1><template shadowrootmode="open"><div>Hellow</div></template></oh-1>').window as any
+    polyfillDSD(window.document)
+
+    const { template } = re(window.document)
+
+    using({ window }).define('oh-1', () => {
+      onHydrated(cb)
+
+      return template`<div>Hi!</div>`
+    })
+
+    expect(cb).toHaveBeenCalledWith(window.document.querySelector('oh-1'))
+  })
+
+  test('is not called when not hydrated.', () => {
+    const cb = jest.fn()
+
+    const window = new JSDOM('<oh-2></oh-2>').window as any
+    polyfillDSD(window.document)
+
+    const { template } = re(window.document)
+
+    using({ window }).define('oh-2', () => {
+      onHydrated(cb)
+
+      return template`<div>Hi!</div>`
+    })
+
+    expect(cb).not.toHaveBeenCalled()
+  })
+})