Add defineProps()

Author: arnoson

README.md

@@ -2,7 +2,7 @@
 
 A very simple way to attach javascript to the DOM. When even [petite-vue](https://github.com/vuejs/petite-vue) or [alpine.js](https://github.com/alpinejs/alpine/) would be too much.
 
-💾 less than 0.5kb (minify and gzip)
+💾 ~ 0.6kb (minify and gzip)
 
 ## Installation
 
@@ -15,19 +15,27 @@ npm i @very-simple/components
 ```js
 // components/gallery.js
 
-import { registerComponent } from '@very-simple/components'
+import { registerComponent, defineProps } from '@very-simple/components'
 
+const props = defineProps({ loop: Boolean })
 registerComponent('gallery', ({ el, ref, refs }) => {
+  // Props are read from el's dataset and automatically converted to the correct
+  // type. Default values are also possible, see documentation.
+  const { loop } = props(el)
+
   // Multiple HTML elements can have the same `ref` name. They will be
   // grouped in `refs` ...
   const { slides } = refs
+
   // ... whereas `ref` only stores a single element per name.
   const { prev, next } = ref
 
   let currentIndex = 0
   const maxIndex = slides.length - 1
 
   const selectSlide = index => {
+    if (!loop && (index < 0 || index > maxIndex)) return
+
     currentIndex = index < 0 ? maxIndex : index > maxIndex ? 0 : index
     slides.forEach((el, index) => (el.hidden = index !== currentIndex))
   }
@@ -44,7 +52,7 @@ registerComponent('gallery', ({ el, ref, refs }) => {
 ```html
 <!-- index.html -->
 
-<div id="my-gallery" data-simple-component="gallery">
+<div id="my-gallery" data-simple-component="gallery" data-loop="true">
   <div data-ref="slides">A</div>
   <div data-ref="slides">B</div>
   <div data-ref="slides">C</div>
@@ -92,6 +100,44 @@ mountComponent(el: HTMLElement)
 mountComponent(root?: HTMLElement)
 ```
 
+### Define Props
+
+Define properties to automatically convert `el.dataset` properties to the
+correct type and enable autocompletion.
+
+```ts
+// You can either define a prop's type by proving a constructor ...
+defineProps({ answer: Number, enabled: Boolean })
+
+// ... or by providing a default value.
+defineProps({ answer: 42, enabled: true })
+
+// For objects and arrays the default value can be wrapped inside a function
+defineProps({ list: () => [1, 2, 3] })
+```
+
+Example:
+
+```ts
+const props = defineProps({
+  enabled: true,
+  message: String,
+  tags: () => ['default']
+})
+
+export default registerComponent('my-component', ({ el }) => {
+  const { enabled, message, tags } = props(el)
+})
+```
+
+```html
+<div
+  data-simple-component="my-component"
+  data-message="Hello"
+  data-tags='[ "very", "simple", "components" ]'
+></div>
+```
+
 ### Ignore Elements
 
 Sometimes it is useful to skip big DOM elements when searching for components

src/index.ts

@@ -1,2 +1,3 @@
 export { registerComponent } from './registerComponent'
 export { mountComponent, mountComponents } from './mountComponent'
+export { defineProps } from './props'

src/props.ts

@@ -0,0 +1,57 @@
+type Constructor =
+  | NumberConstructor
+  | StringConstructor
+  | ArrayConstructor
+  | ObjectConstructor
+  | BooleanConstructor
+
+type Props<T> = {
+  [K in keyof T]: T[K] extends Constructor
+    ? ReturnType<T[K]> | undefined
+    : T[K] extends () => any
+    ? ReturnType<T[K]>
+    : T[K]
+}
+
+const isConstructor = (value: any) =>
+  [Number, String, Boolean, Array, Object].includes(value)
+
+const parse = (value: any, type: string) =>
+  type === 'string'
+    ? String(value)
+    : type === 'number'
+    ? Number(value)
+    : type === 'boolean'
+    ? value !== 'false'
+    : JSON.parse(value)
+
+const getDefaultValue = (definition: any) =>
+  definition instanceof Function ? definition() : definition
+
+export const defineProps = <T>(definitions: T) => {
+  return (el: HTMLElement) => {
+    const props = Object.fromEntries(
+      Object.entries(definitions).map(([key, definition]) => {
+        const serializedValue = el.dataset[key]
+        const providesDefault = !isConstructor(definition)
+
+        const defaultValue = providesDefault
+          ? getDefaultValue(definition)
+          : undefined
+
+        const type = providesDefault
+          ? typeof defaultValue
+          : definition.prototype.constructor.name.toLowerCase()
+
+        const value =
+          serializedValue === undefined
+            ? defaultValue
+            : parse(serializedValue, type)
+
+        return [key, value]
+      })
+    )
+
+    return props as Props<T>
+  }
+}

tests/__snapshots__/index.test.ts.snap

@@ -0,0 +1,43 @@
+// Vitest Snapshot v1
+
+exports[`interferes prop types from default values 1`] = `
+{
+  "array": [
+    1,
+    2,
+    3,
+  ],
+  "bool": true,
+  "number": 1,
+  "obj": {
+    "hello": "world",
+  },
+  "string": "text",
+}
+`;
+
+exports[`parses props 1`] = `
+{
+  "array": [
+    1,
+    2,
+    3,
+  ],
+  "bool": true,
+  "number": 1,
+  "obj": {
+    "hello": "world",
+  },
+  "string": "text",
+}
+`;
+
+exports[`provides default values for props 1`] = `
+{
+  "array": [],
+  "bool": true,
+  "number": 10,
+  "obj": {},
+  "string": "hello",
+}
+`;

tests/index.test.ts

@@ -1,5 +1,10 @@
 import { it, expect, vi } from 'vitest'
-import { registerComponent, mountComponent, mountComponents } from '../src'
+import {
+  registerComponent,
+  mountComponent,
+  mountComponents,
+  defineProps
+} from '../src'
 
 it('mounts a component', () => {
   const component = vi.fn()
@@ -96,6 +101,65 @@ it('provides a record of groups of refs with the same name', () => {
   expect(component).toBeCalledWith(expect.objectContaining({ refs: { myRef } }))
 })
 
+it(`parses props`, () => {
+  document.body.innerHTML = `
+    <div
+      data-number="1"
+      data-string="text"
+      data-bool="true"
+      data-array="[1,2,3]"
+      data-obj='{ "hello": "world" }'
+    ></div>
+  `
+  const el = document.querySelector('div')
+  const readProps = defineProps({
+    number: Number,
+    string: String,
+    bool: Boolean,
+    array: Array,
+    obj: Object
+  })
+
+  expect(readProps(el!)).toMatchSnapshot()
+})
+
+it(`provides default values for props`, () => {
+  document.body.innerHTML = `<div></div>`
+  const el = document.querySelector('div')
+
+  const readProps = defineProps({
+    number: 10,
+    string: 'hello',
+    bool: true,
+    array: () => [],
+    obj: () => ({})
+  })
+
+  expect(readProps(el!)).toMatchSnapshot()
+})
+
+it('interferes prop types from default values', () => {
+  document.body.innerHTML = `
+    <div
+      data-number="1"
+      data-string="text"
+      data-bool="true"
+      data-array="[1,2,3]"
+      data-obj='{ "hello": "world" }'
+    ></div>
+  `
+  const el = document.querySelector('div')
+  const readProps = defineProps({
+    number: 42,
+    string: 'default',
+    bool: false,
+    array: () => [],
+    obj: () => ({})
+  })
+
+  expect(readProps(el!)).toMatchSnapshot()
+})
+
 it(`exposes the component function's return value`, () => {
   const exposed = { test: () => {} }
   registerComponent('test', () => exposed)
@@ -104,5 +168,5 @@ it(`exposes the component function's return value`, () => {
     <div data-simple-component="test" id="my-id"></div>
   `
   mountComponents(document.body)
-  expect(document.getElementById('my-id').$component).toBe(exposed)
+  expect(document.getElementById('my-id')?.$component).toBe(exposed)
 })