Partial docs

Author: noamr

README.md

@@ -1,6 +1,8 @@
 # Velvette
 Making it easier to author CSS View Transitions
 
+For the docs go [here](https://noamr.github.io/velvette/)
+
 ## Tl;dr
 A small JS library that implements common patterns on top of CSS view-transitions:
 * Useful temporary classes while the transition is active
@@ -262,8 +264,3 @@ To apply a `Velvette` configuration for cross-document view transitions:
 new Velvette(config).crossDocument();
 ```
 
-
-
-
-## The API
-

src/index.js

@@ -7,14 +7,40 @@ import { start } from "./transition.js";
 import { init } from "./nav.js";
 
 /**
+ * Starts a {@link https://developer.mozilla.org/en-US/docs/Web/API/ViewTransition ViewTransition} with
+ * additional params. Based on these params, Velvette applies temporary classes to the {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/html document element},
+ * generates {@link https://developer.mozilla.org/en-US/docs/Web/CSS/view-transition-name `view-transition-name`} properties
+ * and adds temporary styles for {@link https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API#the_view_transition_process the `::view-transition-*` pseudo-elements}.
  *
  * @param {object} options
- * @param {() => void | Promise<void>} options.update
- * @param {string[]?} options.classes
- * @param {{[key: string]: Partial<CSSStyleDeclaration>}?} options.styles
- * @param {{[selector: string]: string}?} options.captures
+ * @param {() => void | Promise<void>} options.update The operation that updates the DOM to the new state.
+ * @param {string[]?} options.classes A list of temporary classes to be applied to the document element with a `vt-` prefix during the course of the transition.
+ * @param {{[key: string]: Partial<CSSStyleDeclaration>}?} options.styles A map of styles, see {@link Config#styles}
+ * @param {{[selector: string]: string}?} options.captures A map of captures, see {@link Config#captures}
  *
  * @returns {ViewTransition | null}
+ *
+ * @example
+ * import {startViewTransition} from "velvette";
+ * // This will return a ViewTransition, or a null if this browser doesn't support CSS View Transitions.
+ * startViewTransition({
+ *   async update() {
+ *     // Make actual DOM update
+ *   },
+ *
+ *   // This would apply `vt-slide-in` on the root element for the duration of the transition
+ *   classes: ["slide-in"],
+ *
+ *   // This would capture any `li.item .box`, and would give it the `view-transition-name`
+ *   // corresponding to "box-" plus its ancestor `li.item`'s id.
+ *   // In addition, it would apply any style with a pseudo that matches '.any-box' to all the
+ *   // captured elements.
+ *   captures: { "li.item[:id] .box": "box-$(id).any-box" }
+ *
+ *   // Would apply a blur during the transition, to the transition group generated
+ *   // for any capture that matches the ".any-box".
+ *   styles: {"::view-transition-group(.any-box)": {filter: "blur(1px)"}},
+ * });
  */
 export function startViewTransition(options) {
     if (!("startViewTransition" in document)) {
@@ -46,20 +72,43 @@ export class VelvetteEvent extends Event {
     }
 }
 
+/**
+ * Constructs an object that takes a {@link Config} param and can then perform view transitions
+ * based on navigations. There are 3 ways to invoke a navigation-based transition:
+ *
+ * - Programatically, via {@link Velvette#startNavigation Velvette.startNavigation}
+ * - Same-document: by {@link Velvette#intercept intercepting} a navigation using the {@link https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API Navigation API}
+ * - Cross-document: by attaching to the window's events {@link Velvette#crossDocument Velvette.crossDocument}. Note that this doesn't work in stable browsers yet.
+ *
+ * See {@link Config} for the different configuration options.
+ */
 export class Velvette {
     #internal;
-    /**  @param {Config} config */
+    /**  @param {Config} config The configuration object that defines how to handle each navigation */
     constructor(config) {
         this.#internal = init(config);
     }
 
     /**
      * @param {object} navigation
-     * @param {string} navigation.from
-     * @param {string} navigation.to
-     * @param {NavigationType} navigation.navigationType
-     * @param {number} navigation.traverseDelta
-     * @param {() => void | Promise<void>} update
+     * @param {string} navigation.from The previous URL of the navigation
+     * @param {string} navigation.to The next URL of the navigation
+     * @param {NavigationType} navigation.navigationType The type of navigation (push/replace/reload/traverse)
+     * @param {number} navigation.traverseDelta If this is a `traverse` navigation, the delta. E.g. -1 is "back".
+     * @param {() => void | Promise<void>} update The operation that updates the DOM based on the navigation.
+     *
+     * @example
+     *
+     * const velvette = new Velvette(config);
+     * link.addEventListener("click", event => {
+     *     velvette.startNavigation({
+     *         from: document.URL,
+     *         to: event.target.href,
+     *         navigationType: "push",
+     *     }, () => {
+     *        // Make actual DOM change.
+     *     });
+     * });
      */
     startNavigation(navigation, update) {
         const result = this.#internal.findMatchingNav(navigation);
@@ -73,9 +122,22 @@ export class Velvette {
     }
 
     /**
-     * @param {NavigateEvent} event
+     * @param {NavigateEvent} event A `NavigateEvent`
      * @param {{handler: () => Promise<void>}} interceptor
      * @return {Promise<ViewTransition | null>}
+     *
+     * @example
+     * const velvette = new Velvette(config);
+     * window.navigation.addEventListener("navigate", event => {
+     *   if (shouldInterceptEvent(event)) {
+     *       // This would potentially start a transition based on the configuration.
+     *       velvette.intercept(event, {
+     *              async handler() {
+     *                 // Make actual DOM change
+     *              }
+     *          });
+     *       });
+     *   }
      */
     intercept(event, interceptor) {
         const nav = this.#internal.findMatchingNavForNavigateEvent(event);
@@ -124,7 +186,8 @@ export class Velvette {
          * @returns {void}
          */
         const toggle = enabled => {
-            styleRule.navigation = enabled ? "auto" : "none"};
+            styleRule.navigation = enabled ? "auto" : "none"
+        };
 
         window.addEventListener("pagehide", () => toggle(true));
         window.addEventListener("pagereveal", event => {

tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "files": ["src/index.js"],
+  "files": ["src/index.js", "src/global.d.ts", "src/types.ts"],
   "compilerOptions": {
     /* Visit https://aka.ms/tsconfig to read more about this file */
 

typedoc.json

@@ -1,5 +1,5 @@
 {
-  "entryPoints": ["src/index.js"],
+  "entryPoints": ["src/index.js", "src/types.ts", "src/global.d.ts"],
   "readme": "README.md",
   "out": "./docs"
 }