readme and enable cd

nruffing · Jan 3, 2024 · c333d07 · c333d07
1 parent c5ad7f5
commit c333d07
Show file tree

Hide file tree

Showing 4 changed files with 182 additions and 58 deletions.
diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml
@@ -67,58 +67,58 @@ jobs:
         cache: 'pnpm'
     - run: pnpm run ci-e2e:linux
 
-  # build_and_publish:
-  #   runs-on: ubuntu-latest
-  #   needs: [ci]
-  #   if: github.ref == 'refs/heads/main'    
-  #   env:
-  #     EXISTING_VERSIONS: ''
-  #     NODE_VERSION: 18.x
-  #     SHOULD_PUBLISH: false
-  #   steps:
-  #   - uses: actions/checkout@v4
-  #   - name: Install pnpm
-  #     uses: pnpm/action-setup@v2
-  #   - name: Use Node.js ${{ env.NODE_VERSION }}
-  #     uses: actions/setup-node@v3
-  #     with:
-  #       registry-url: 'https://registry.npmjs.org'
-  #       node-version: ${{ env.NODE_VERSION }}
-  #       cache: 'pnpm'
-  #   - run: pnpm run ci-all
-  #   - name: Parse package version
-  #     run: echo "VERSION=$(grep -Po '(?<=\"version\":\s\")\d+\.\d+\.\d+(?=\")' ./package.json)" >> $GITHUB_ENV
-  #   - name: Get existing versions from NuGet
-  #     run: echo "EXISTING_VERSIONS=$(pnpm show ${{ env.PACKAGE_NAME }} versions --json | tr -d '\r\n ')" >> $GITHUB_ENV
-  #   - name: Detect new version
-  #     run: echo "SHOULD_PUBLISH=$(echo ${{ env.VERSION != '' && fromJson(env.EXISTING_VERSIONS) != 0 && (contains(fromJson(env.EXISTING_VERSIONS), env.VERSION) == false) }} )" >> $GITHUB_ENV
-  #   - name: Publish
-  #     if: fromJson(env.SHOULD_PUBLISH)
-  #     run: npm publish --provenance
-  #     env:
-  #       NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-  #   outputs:
-  #     should_publish: ${{ env.SHOULD_PUBLISH }}
+  build_and_publish:
+    runs-on: ubuntu-latest
+    needs: [ci]
+    if: github.ref == 'refs/heads/main'    
+    env:
+      EXISTING_VERSIONS: ''
+      NODE_VERSION: 18.x
+      SHOULD_PUBLISH: false
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install pnpm
+      uses: pnpm/action-setup@v2
+    - name: Use Node.js ${{ env.NODE_VERSION }}
+      uses: actions/setup-node@v3
+      with:
+        registry-url: 'https://registry.npmjs.org'
+        node-version: ${{ env.NODE_VERSION }}
+        cache: 'pnpm'
+    - run: pnpm run ci-all
+    - name: Parse package version
+      run: echo "VERSION=$(grep -Po '(?<=\"version\":\s\")\d+\.\d+\.\d+(?=\")' ./package.json)" >> $GITHUB_ENV
+    - name: Get existing versions from NuGet
+      run: echo "EXISTING_VERSIONS=$(pnpm show ${{ env.PACKAGE_NAME }} versions --json | tr -d '\r\n ')" >> $GITHUB_ENV
+    - name: Detect new version
+      run: echo "SHOULD_PUBLISH=$(echo ${{ env.VERSION != '' && fromJson(env.EXISTING_VERSIONS) != 0 && (contains(fromJson(env.EXISTING_VERSIONS), env.VERSION) == false) }} )" >> $GITHUB_ENV
+    - name: Publish
+      if: fromJson(env.SHOULD_PUBLISH)
+      run: npm publish --provenance
+      env:
+        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+    outputs:
+      should_publish: ${{ env.SHOULD_PUBLISH }}
 
-  # create_release:
-  #   runs-on: ubuntu-latest
-  #   needs: [build_and_publish]
-  #   if: fromJson(needs.build_and_publish.outputs.should_publish)
-  #   env:
-  #     ESCAPED_VERSION: ''
-  #   steps:
-  #     - uses: actions/checkout@v4
-  #     - name: Parse package version
-  #       run: echo "VERSION=$(grep -Po '(?<=\"version\":\s\")\d+\.\d+\.\d+(?=\")' ./package.json)" >> $GITHUB_ENV
-  #     - name: Escape version
-  #       run: echo "ESCAPED_VERSION=$(echo "${{ env.VERSION }}" | sed 's/[^^]/[&]/g; s/\^/\\^/g')" >> $GITHUB_ENV
-  #     - name: Parse release notes
-  #       run: (grep -Pzo '(?<=### v${{ env.ESCAPED_VERSION }}\n)\X+?(?=\n\n)' ./README.md) | tr -d '\0' > release_notes.txt
-  #     - name: Create release
-  #       uses: actions/create-release@latest
-  #       env:
-  #         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-  #       with:
-  #         tag_name: v${{ env.VERSION }}
-  #         release_name: v${{ env.VERSION }}
-  #         body_path: ${{ github.workspace }}/release_notes.txt
+  create_release:
+    runs-on: ubuntu-latest
+    needs: [build_and_publish]
+    if: fromJson(needs.build_and_publish.outputs.should_publish)
+    env:
+      ESCAPED_VERSION: ''
+    steps:
+      - uses: actions/checkout@v4
+      - name: Parse package version
+        run: echo "VERSION=$(grep -Po '(?<=\"version\":\s\")\d+\.\d+\.\d+(?=\")' ./package.json)" >> $GITHUB_ENV
+      - name: Escape version
+        run: echo "ESCAPED_VERSION=$(echo "${{ env.VERSION }}" | sed 's/[^^]/[&]/g; s/\^/\\^/g')" >> $GITHUB_ENV
+      - name: Parse release notes
+        run: (grep -Pzo '(?<=### v${{ env.ESCAPED_VERSION }}\n)\X+?(?=\n\n)' ./README.md) | tr -d '\0' > release_notes.txt
+      - name: Create release
+        uses: actions/create-release@latest
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: v${{ env.VERSION }}
+          release_name: v${{ env.VERSION }}
+          body_path: ${{ github.workspace }}/release_notes.txt
diff --git a/README.md b/README.md
@@ -6,10 +6,126 @@ Directives and composables for wiring up and debouncing native HTML events in Vu
   <a href="https://github.com/nruffing/native-event-vue/actions/workflows/ci_cd.yml">
     <img src="https://github.com/nruffing/native-event-vue/actions/workflows/ci_cd.yml/badge.svg" />
   </a>
-  <!-- <a href="https://www.npmjs.com/package/native-event-vue" target="_blank" aria-label="npm">
+  <a href="https://www.npmjs.com/package/native-event-vue" target="_blank" aria-label="npm">
     <img alt="npm" src="https://img.shields.io/npm/v/native-event-vue?logo=npm" />
-  </a> -->
+  </a>
   <a href="https://github.com/nruffing/native-event-vue/blob/main/LICENSE" aria-label="MIT License">
     <img alt="GitHub" src="https://img.shields.io/github/license/nruffing/native-event-vue" />
   </a>
-</p>
+</p>
+
+## Install
+
+```
+npm i native-event-vue
+```
+
+## Setup
+
+```ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import { NativeEventVue } from 'dragon-drop-vue'
+
+createApp(App).use(NativeEventVue)
+```
+
+### Plugin Options (i.e. NativeEventVueOptions)
+
+```ts
+import { createApp } from 'vue'
+import App from './App.vue'
+import { NativeEventVue, type NativeEventVueOptions } from 'dragon-drop-vue'
+
+const options = {
+  debugLog: true,
+} as NativeEventVueOptions
+
+createApp(App).use(NativeEventVue, options)
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `debugLog` | `boolean` or `undefined` | Print additional debugging information to the console. |
+| `nativeEventDirectiveName` | `string` or `undefined` | Optionally specify what to register for the native-event directive. By default this is `native-event` and the directive would be `v-native-event`. |
+| `propNamePrefix` | `string` or `undefined` | When an event is attached using this library a reference to the the libraries event instance is stored on the attached element using a property prefixed with this value and ending in the event name. This defaults to `native-event-vue-`. |
+
+## Usage
+
+Native HTML events can be attached and debounced using either the `v-native-event` directive or the `useNativeEvent` composable depending on your situation.
+
+When using the directive the event and debounce timeouts are automatically destroyed in the directive's `beforeUnmount` hook. When using the composable the destroy function needs to be called explicitly.
+
+### Directive
+
+The following example demonstrates how to use the `v-native-event` directive to wire-up a native html event. In this example the input event is used to show a simple and easy to follow example but you likely would not need this package for the input event unless you wanted to debounce it. If you can use the built-in native event handling of Vue or `v-model` that is the recommended approach.
+
+```vue
+<template>
+  <main>
+    <input
+      id="input"
+      v-native-event="{ event: 'input', listener, debounceMs: 300 }"
+    />
+    <span id="input-value">{{ inputValue }}</span>
+  </main>
+</template>
+
+<script lang="ts" setup>
+import { ref } from 'vue'
+
+const inputValue = ref('')
+
+function listener(event: Event) {
+  const input = event.target as HTMLInputElement
+  inputValue.value = input.value
+}
+</script>
+```
+
+#### Directive Options (i.e. NativeEventOptions)
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `event` | `string` | The name of the native event (e.g. `resize`). |
+| `listener` | `EventListenerOrEventListenerObject` | The event handler function to attach. This is the same type as the browser API [`addEventListener.listener` parameter](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#the_event_listener_callback). |
+| `options` | `boolean`, `AddEventListenerOptions` or `undefined` | Optional. This is the same type as the browser API [`addEventListener.options` parameter](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options). |
+| `debounceMs` | `number` or `undefined` | Optionally specify a debounce timeout. |
+| `disabled` | `boolean` or `undefined` | Optionally disable/remove the event handler. |
+
+### Composable
+
+```vue
+<script lang="ts">
+import { ref, onMounted, onBeforeUnmount } from 'vue'
+import { useNativeEvent, type NativeEvent } from 'native-event-vue'
+
+const nativeEvent = ref<NativeEvent>(undefined)
+
+function onWindowResize(event: Event) { ... }
+
+onMounted(() => {
+  nativeEvent.value = useNativeEvent(window, 'resize', onWindowResize, undefined, 300)
+})
+
+onBeforeUnmount(() => {
+  nativeEvent.value?.destroy()
+})
+</script>
+```
+
+#### Composable Parameters
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `domEl` | `HTMLElement` | The DOM element to attach the event listener to. |
+| `event` | `string` | The name of the native event (e.g. `resize`). |
+| `listener` | `EventListenerOrEventListenerObject` | The event handler function to attach. This is the same type as the browser API [`addEventListener.listener` parameter](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#the_event_listener_callback). |
+| `options` | `boolean`, `AddEventListenerOptions` or `undefined` | Optional. This is the same type as the browser API [`addEventListener.options` parameter](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options). |
+| `debounceMs` | `number` or `undefined` | Optionally specify a debounce timeout. |
+| `replaceExisting` | `boolean` or `undefined` | Optionally specify to replace any existing event handler that was attached using `native-event-vue`. Otherwise the new event listener will not be attached. |
+
+## Release Notes
+
+### v1.0.0
+  * Initial release
diff --git a/cspell.json b/cspell.json
@@ -26,6 +26,7 @@
     "typecheck",
     "vitest",
     "vnode",
+    "vuejs",
     "vuepress",
     "webdriverio",
     "xmldocmd"

diff --git a/package.json b/package.json
@@ -17,7 +17,14 @@
   "bugs": {
     "url": "https://github.com/nruffing/native-event-vue/issues"
   },
-  "keywords": [],
+  "keywords": [
+    "html event",
+    "native event",
+    "event",
+    "vuejs",
+    "vue",
+    "vue3"
+  ],
   "packageManager": "[email protected]",
   "engines": {
     "node": ">=18"