tweak docs

yyx990803 · yyx990803 · commit 1992ad676948 · 2021-07-01T12:49:16.000-04:00
diff --git a/README.md b/README.md
@@ -1,33 +1,54 @@
-# petite-vue (WIP)
+# petite-vue
 
-A subset of Vue optimized for progressive enhancement.
+`petite-vue` is a subset of Vue optimized for progressive enhancement. It provides the same template syntax and reactivity mental model with standard Vue. However, it is specifically optimized for "sprinkling" small amount of interactions on an existing HTML page rendered by a server framework.
 
-- 5.5kb w/ most non-component features
+- 5.5kb min+brotli w/ most non-component features
 - DOM-based, mutates in place
 - Driven by `@vue/reactivity`
 
 ## Usage
 
+`petite-vue` has one special directive: `v-scope` that is not present in standard Vue. Use it to mark regions on the page that should be controlled by `petite-vue`:
+
 ```html
-<script type="module">
-  import { createApp } from 'petite-vue'
-  createApp().mount()
-</script>
+<script src="https://unpkg.com/petite-vue" defer init></script>
 
-<div v-scope="{ text: 'hello', open: true }">
-  {{ text }}
-  <input v-model="text" v-if="open" />
-  <button @click="open = !open">toggle</button>
+<!-- anywhere on the page -->
+<div v-scope="{ count: 0 }">
+  {{ count }}
+  <button @click="count++">inc</button>
 </div>
 ```
 
-### Reusing Logic
+The `defer` attribute makes the script execute after HTML content is parsed, and `init` tells `petite-vue` to automatically query and initialize all elements that have `v-scope` on the page.
 
-There are no components, but logic can be shared across the app or encapsulated in setup-like functions:
+### Manual Init
+
+If you don't want the auto init, remove the `init` attribute and move the scripts to end of `<body>`:
+
+```html
+<script src="https://unpkg.com/petite-vue"></script>
+<script>
+  PetiteVue.createapp().mount()
+</script>
+```
+
+Or, use the ES modules build:
+
+```html
+<script type="module">
+  import { createApp } from 'https://unpkg.com/petite-vue?module'
+  createApp().mount()
+<script>
+```
+
+### Global Data
+
+The `createApp` function accepts a data object that serves as the root scope for all expressions. This can be used for simple global state management:
 
 ```html
 <script type="module">
-  import { createApp, reactive } from 'petite-vue'
+  import { createApp, reactive } from 'https://unpkg.com/petite-vue?module'
 
   const store = reactive({
     count: 0,
@@ -36,42 +57,122 @@ There are no components, but logic can be shared across the app or encapsulated
     }
   })
 
-  function ComponentLike(count) {
+  createApp({
+    // exposed to all expressions
+    store
+  }).mount()
+</script>
+
+<div v-scope="{ localCount: 0 }">
+  <p>Global {{ store.count }}</p>
+  <button @click="store.inc">increment</button>
+
+  <p>Local {{ localCount }}</p>
+  <button @click="localCount++">increment</button>
+</div>
+```
+
+### Reusing Logic
+
+There are no components, but logic can be shared across the app or encapsulated in setup-like functions:
+
+```html
+<script type="module">
+  import { createApp } from 'https://unpkg.com/petite-vue?module'
+
+  function ComponentLike(props) {
     return {
-      count,
+      count: props.initialCount,
       inc() {
         this.count++
       }
     }
   }
 
   createApp({
-    // exposed to all expressions
-    store,
     ComponentLike
   }).mount()
 </script>
 
-<div v-scope="ComponentLike(10)">
-  <p>Global {{ store.count }}</p>
-  <button @click="store.inc">increment</button>
-
-  <p>Local {{ count }}</p>
+<div v-scope="ComponentLike({ initialCount: 10 })">
+  <p>{{ count }}</p>
   <button @click="inc">increment</button>
 </div>
 ```
 
-## Differences
+### Custom Directives
+
+Custom directives are also supported but with a different interface:
+
+```js
+const myDirective = (ctx) => {
+  // the element the directive is on
+  ctx.el
+  // the raw value expression
+  // e.g. v-my-dir="x" then this would be "x"
+  ctx.exp
+  // v-my-dir:foo -> "foo"
+  ctx.arg
+  // v-my-dir.mod -> { mod: true }
+  ctx.modifiers
+  // evaluate the expression and get its value
+  ctx.get()
+  // evaluate arbitrary expression in current scope
+  ctx.get(`${ctx.exp} + 10`)
+
+  // run reactive effect
+  ctx.effect(() => {
+    // this will re-run every time the get() value changes
+    console.log(ctx.get())
+  })
+
+  return () => {
+    // cleanup if the element is unmounted
+  }
+}
+
+// register the directive
+createApp().directive('my-dir', myDirective).mount()
+```
+
+This is how `v-html` is implemented:
+
+```js
+const html = ({ el, get, effect }) => {
+  effect(() => {
+    el.innerHTML = get()
+  })
+}
+```
 
-Custom directive interface is different. (TODO document)
+## Supported Features
+
+- `{{ }}` text bindings
+- `v-bind` (including `:` shorthand and class/style special handling)
+- `v-on` (including `@` shorthand and all modifiers)
+- `v-model` (all input types + non-string `:value` bindings)
+- `v-if` / `v-else` / `v-else-if`
+- `v-for`
+- `v-show`
+- `v-html`
+- `v-text`
+- `v-pre`
+- `v-cloak`
+- `reactive()`
+- Custom directives (see above).
 
 ## Not Supported
 
-- `ref`
-- Reactivity for Collection Types (Map, Set, etc.)
-- Components
+Some features are dropped because they have a relatively low size/utility ratio in the context of progressive enhancement. If you need these features, you should probably just use standard Vue.
+
+- `ref()`, `computed()` etc.
+- Components (see "Reuse Logic" section above)
+- Template refs (just use selectors)
+- Render functions (`petite-vue` has no virtual DOM)
+- Reactivity for Collection Types (Map, Set, etc., removed for smaller size)
 - Transition, KeepAlive, Teleport, KeepAlive
-- `v-on` object syntax
+- `v-for` deep destructure
+- `v-on="object"`
 - `v-once`
-- `v-is`
-- style auto-prefixing
+- `v-is` & `<component :is="xxx">`
+- `v-bind:style` auto-prefixing
diff --git a/index.html b/index.html
@@ -1,7 +1,7 @@
 <style>
-a {
-  font-size: 18px;
-}
+  a {
+    font-size: 18px;
+  }
 </style>
 <ul>
   <li><a href="/demos/data.html">v-scope</a></li>
@@ -11,4 +11,9 @@
   <li><a href="/demos/for.html">v-for</a></li>
   <li><a href="/demos/model.html">v-model</a></li>
   <li><a href="/demos/reuse.html">Logic Reuse</a></li>
-</ul>
+</ul>
+
+<div v-scope="{ count: 0 }">
+  {{ count }}
+  <button @click="count++">inc</button>
+</div>
diff --git a/package.json b/package.json
@@ -4,7 +4,9 @@
   "files": [
     "dist"
   ],
-  "main": "dist/vue-lite.umd.js",
+  "main": "dist/petite-vue.umd.js",
+  "unpkg": "dist/petite-vue.iife.js",
+  "jsdelivr": "dist/petite-vue.iife.js",
   "module": "./dist/vue-lite.es.js",
   "exports": {
     ".": {
diff --git a/src/directives/text.ts b/src/directives/text.ts
@@ -1,7 +1,7 @@
 import { isObject } from '@vue/shared'
 import { Directive } from '.'
 
-export const text: Directive<Text> = ({ el, exp, get, effect }) => {
+export const text: Directive<Text> = ({ el, get, effect }) => {
   effect(() => {
     el.data = toDisplayString(get())
   })
diff --git a/src/index.ts b/src/index.ts
@@ -1,2 +1,9 @@
 export { createApp } from './app'
 export { reactive, effect } from '@vue/reactivity'
+
+import { createApp } from './app'
+
+let s
+if ((s = document.currentScript) && s.hasAttribute('init')) {
+  createApp().mount()
+}
diff --git a/vite.config.ts b/vite.config.ts
@@ -7,7 +7,8 @@ export default defineConfig({
     // minify: false,
     lib: {
       entry: resolve(__dirname, 'src/index.ts'),
-      name: 'PetiteVue'
+      name: 'PetiteVue',
+      formats: ['es', 'umd', 'iife']
     },
     rollupOptions: {
       plugins: [
