@multitrack/vue 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present Jack Hsu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,171 @@
+# @multitrack/vue
+
+Vue 3 bindings for [`@multitrack/core`](https://github.com/jakhsu/multitrack/tree/main/packages/core) — a scroll-driven animation engine with a multi-track timeline architecture.
+
+## Install
+
+```bash
+npm install @multitrack/core @multitrack/vue
+```
+
+## Quick start
+
+```vue
+<script setup lang="ts">
+import { MultitrackProvider, ScrollContainer, FixedStage, Show, useStep } from "@multitrack/vue";
+import type { StepConfig } from "@multitrack/core";
+
+const config: StepConfig[] = [
+  { name: "intro", duration: 3, track: "main", easing: "linear" },
+  { name: "feature", duration: 5, track: "main" },
+  { name: "outro", duration: 3, track: "main", easing: "linear" },
+];
+</script>
+
+<template>
+  <MultitrackProvider :config="config">
+    <ScrollContainer>
+      <FixedStage>
+        <Show when="intro">
+          <IntroSection />
+        </Show>
+        <Show when="feature">
+          <FeatureSection />
+        </Show>
+      </FixedStage>
+    </ScrollContainer>
+  </MultitrackProvider>
+</template>
+```
+
+```vue
+<!-- IntroSection.vue -->
+<script setup lang="ts">
+import { useStep } from "@multitrack/vue";
+
+const { opacity } = useStep("intro");
+</script>
+
+<template>
+  <div :style="{ opacity: opacity, transform: `translateY(${(1 - opacity) * 40}px)` }">
+    <h1>Welcome</h1>
+  </div>
+</template>
+```
+
+## API
+
+### `<MultitrackProvider>`
+
+Wraps your app and creates the timeline instance. All composables and components must be used within this provider.
+
+```vue
+<MultitrackProvider :config="config" :breakpoints="breakpoints" devtools>
+  <slot />
+</MultitrackProvider>
+```
+
+### Composables
+
+#### `useStep(name)`
+
+Returns `{ opacity, isActive }` as Vue `computed` refs for a single step.
+
+#### `useOpacities()`
+
+Returns a `computed` ref containing an `Opacities` record (`{ [stepName]: number }`) for all steps.
+
+#### `useScrollProgress()`
+
+Returns `{ scrollPercentage, currentStep, totalSteps }` as `computed` refs.
+
+#### `useTimeline()`
+
+Returns the underlying `Timeline` instance for advanced use cases.
+
+### Components
+
+#### `<ScrollContainer>`
+
+The scrollable container that drives the timeline. Renders a `<div>` with the correct scroll height.
+
+#### `<FixedStage>`
+
+A fixed-position overlay inside `ScrollContainer` for content that stays in the viewport while scrolling.
+
+#### `<Show when="stepName">`
+
+Conditionally renders children when the named step is active (opacity > 0).
+
+### DevTools
+
+Enable the Chrome DevTools integration by passing the `devtools` prop to the provider:
+
+```vue
+<MultitrackProvider :config="config" devtools>
+  <slot />
+</MultitrackProvider>
+```
+
+This exposes timeline state to the [@multitrack/devtools](https://github.com/jakhsu/multitrack/tree/main/packages/devtools) Chrome extension, giving you a live timeline inspector with playhead visualization, active step opacities, and an event log.
+
+## Full example with `useStep()`
+
+For fine-grained control over individual steps, use the `useStep()` composable to get `{ opacity, isActive }` computed refs and drive animations directly:
+
+```vue
+<script setup lang="ts">
+import { MultitrackProvider, ScrollContainer, FixedStage, Show } from "@multitrack/vue";
+import type { StepConfig } from "@multitrack/core";
+import IntroSection from "./IntroSection.vue";
+import FeatureSection from "./FeatureSection.vue";
+import Caption from "./Caption.vue";
+
+const config: StepConfig[] = [
+  { name: "intro", duration: 3, track: "main", easing: "linear" },
+  { name: "feature", duration: 5, track: "main" },
+  { name: "outro", duration: 3, track: "main", easing: "linear" },
+
+  // Independent text track — overlaps freely with main
+  { name: "buffer", duration: 4, track: "text" },
+  { name: "caption", duration: 3, track: "text" },
+];
+</script>
+
+<template>
+  <MultitrackProvider :config="config" devtools>
+    <ScrollContainer>
+      <FixedStage>
+        <Show when="intro">
+          <IntroSection />
+        </Show>
+        <Show when="feature">
+          <FeatureSection />
+        </Show>
+        <Show when="caption">
+          <Caption text="Tracks are independent." />
+        </Show>
+      </FixedStage>
+    </ScrollContainer>
+  </MultitrackProvider>
+</template>
+```
+
+```vue
+<!-- IntroSection.vue -->
+<script setup lang="ts">
+import { useStep } from "@multitrack/vue";
+
+const { opacity } = useStep("intro");
+</script>
+
+<template>
+  <div :style="{ opacity: opacity, transform: `translateY(${(1 - opacity) * 40}px)` }">
+    <h1>Welcome</h1>
+  </div>
+</template>
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multitrack/vue",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Vue 3 bindings for @multitrack/core",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -18,16 +18,14 @@
       }
     }
   },
-  "files": ["dist"],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch"
-  },
+  "files": [
+    "dist"
+  ],
   "peerDependencies": {
     "vue": ">=3.3.0"
   },
   "dependencies": {
-    "@multitrack/core": "workspace:^"
+    "@multitrack/core": "^0.1.1"
   },
   "sideEffects": false,
   "license": "MIT",
@@ -56,5 +54,9 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
   }
-}
+}