Merge pull request #11 from wethegit/feature/v4-docs

feature: v4 docs

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wethegit/preact-stickerbook",
-  "version": "4.0.0-beta.1",
+  "version": "4.0.0-beta.2",
   "description": "Easily create collage apps that are accessible by default.",
   "files": [
     "dist/*"

src/app.tsx

@@ -1,8 +1,9 @@
 import { h } from "preact"
-import { useState, useRef, useCallback } from "preact/hooks"
+import { useRef, useCallback } from "preact/hooks"
 
 import { Sticker, Stickerbook } from "./lib"
 import { addSticker, exportStickerbook } from "./lib/helpers"
+import { useStickerbook } from "./lib/use-stickerbook"
 
 import backgroundImage from "./background.jpg"
 import backgroundImage2 from "./background-2.png"
@@ -11,8 +12,6 @@ import foregroundImage from "./foreground.png"
 import foregroundImage2 from "./foreground-2.png"
 import stickerImage from "./sticker.png"
 
-import { useStickerbook } from "./lib/use-stickerbook"
-
 const CANVAS_SIZE = {
   width: 500,
   height: 500,
@@ -69,22 +68,25 @@ export function App() {
 
   const downloadRef = useRef<HTMLAnchorElement | null>(null)
 
-  const [hidden, setHidden] = useState(false)
-
   const onAddSticker = useCallback(async () => {
-    const res = await fetch(GIPHY_API_URL).then((res) => res.json())
-    const {
-      data: {
-        images: {
-          preview_gif: { url },
+    try {
+      const res = await fetch(GIPHY_API_URL).then((res) => res.json())
+
+      const {
+        data: {
+          images: {
+            preview_gif: { url },
+          },
+          caption,
         },
-        caption,
-      },
-    } = res
-
-    setStickers((stickers) =>
-      addSticker(stickers, { image: url, alt: caption })
-    )
+      } = res
+
+      setStickers((stickers) =>
+        addSticker({ stickers, sticker: { image: url, alt: caption } })
+      )
+    } catch (err) {
+      console.error(err)
+    }
   }, [setStickers])
 
   // Download
@@ -117,42 +119,35 @@ export function App() {
 
       <a ref={downloadRef} hidden={true} href="#" download="Stickerbook.png" />
 
-      {/* Toggle button for testing re-renders */}
-      <button onClick={() => setHidden((state) => !state)}>
-        {hidden ? "show" : "hide"} stickerbook
-      </button>
-
-      {!hidden && (
-        <div
-          style={Object.entries(CANVAS_SIZE).reduce((acc, [key, val]) => {
-            return { ...acc, [`max-${key}`]: `${val}px` }
-          }, {})}
+      <div
+        style={Object.entries(CANVAS_SIZE).reduce((acc, [key, val]) => {
+          return { ...acc, [`max-${key}`]: `${val}px` }
+        }, {})}
+      >
+        <Stickerbook
+          outputWidth={CANVAS_SIZE.width}
+          outputHeight={CANVAS_SIZE.height}
+          backgrounds={backgrounds}
+          frame={frame}
+          foregrounds={foregrounds}
         >
-          <Stickerbook
-            outputWidth={CANVAS_SIZE.width}
-            outputHeight={CANVAS_SIZE.height}
-            backgrounds={backgrounds}
-            frame={frame}
-            foregrounds={foregrounds}
-          >
-            {stickers.map((sticker) => (
-              <Sticker
-                key={sticker.id}
-                initialPosition={sticker.position}
-                initialRotation={sticker.rotation}
-                initialScale={sticker.scale}
-                onReorder={onReorderSticker}
-                onDelete={onDeleteSticker}
-                onPosition={onPositionSticker}
-                onScale={onScaleSticker}
-                onRotate={onRotateSticker}
-                disableRotation={sticker.disableRotation}
-                {...sticker}
-              />
-            ))}
-          </Stickerbook>
-        </div>
-      )}
+          {stickers.map((sticker) => (
+            <Sticker
+              key={sticker.id}
+              initialPosition={sticker.position}
+              initialRotation={sticker.rotation}
+              initialScale={sticker.scale}
+              onReorder={onReorderSticker}
+              onDelete={onDeleteSticker}
+              onPosition={onPositionSticker}
+              onScale={onScaleSticker}
+              onRotate={onRotateSticker}
+              disableRotation={sticker.disableRotation}
+              {...sticker}
+            />
+          ))}
+        </Stickerbook>
+      </div>
 
       <a href="https://giphy.com/" target="_blank" rel="noreferrer">
         <img

src/lib/helpers/addSticker.ts

@@ -1,11 +1,19 @@
 import type { StickerItem } from "../types"
 
-type StickerOption = Omit<StickerItem, "id" | "order">
+interface AddStickerOptions {
+  stickers: StickerItem[]
+  sticker: Omit<StickerItem, "id" | "order">
+}
 
-export function addSticker(
-  stickers: StickerItem[] = [],
-  sticker: StickerOption
-) {
+/**
+ * Returns a copy of the provided `stickers` array with the new sticker containing the required **id** and **order** fields.
+ * @param {StickerOptions[]}
+ * @returns {StickerItem[]}
+ */
+export function addSticker({
+  stickers = [],
+  sticker,
+}: AddStickerOptions): StickerItem[] {
   if (!sticker) throw Error("No `sticker` provided")
 
   // we add a unique key based on the time because otherwise the

src/lib/helpers/consts.ts

@@ -1,5 +1,10 @@
 export const ORDER_DIRECTIONS = ["up", "down"] as const
 
+/**
+ * The types of overlays that can be used in the Stickerbook
+ * `scene` - a full-size image that covers the entire Stickerbook. Behaves like `background-size: cover`
+ * `pattern` - a repeating image that covers the entire Stickerbook.
+ */
 export const OVERLAY_TYPES = ["scene", "pattern"] as const
 
 export const EXPORT_FORMATS = ["image", "canvas", "blob"] as const

src/lib/helpers/deleteSticker.ts

@@ -1,6 +1,19 @@
 import type { StickerItem } from "../types"
 
-export function deleteSticker(stickers: StickerItem[], id: string) {
+interface DeleteStickerOptions {
+  stickers: StickerItem[]
+  id: string
+}
+
+/**
+ * Returns a copy of the provided `stickers` array without the selected sticker.
+ * @param {DeleteStickerOptions}
+ * @returns {StickerItem[]}
+ */
+export function deleteSticker({
+  stickers,
+  id,
+}: DeleteStickerOptions): StickerItem[] {
   if (!stickers || !(stickers instanceof Array) || stickers.length <= 0)
     throw Error("`stickers` array is empty")
 

src/lib/helpers/exportStickerbook.ts

@@ -12,13 +12,27 @@ import { renderSticker } from "./renderSticker"
 import { EXPORT_FORMATS } from "./consts"
 
 interface ExportStickerbookOptions<T extends ExportFormat> {
+  /**
+   * A canvas element to draw to. If not provided, a new canvas will be created.
+   */
   canvas?: HTMLCanvasElement
   backgrounds?: BackgroundItem[]
   frame?: Frame
   stickers?: StickerItem[]
   foregrounds?: ForegroundItem[]
+  /**
+   * The width of the output image.
+   */
   outputWidth: number
+  /**
+   * The height of the output image.
+   */
   outputHeight: number
+  /**
+   * **`image`** will generate a url using `window.URL.createObjectURL`
+   * **`canvas`** will just return the provided `canvas` or a new one
+   * **`blob`** will return a `Blob` using `HTMLCanvasElement.toBlob()`
+   */
   format: T
 }
 
@@ -29,6 +43,11 @@ type ExportReturn<K extends ExportFormat> =
   K extends "image" ? string :
   never
 
+/**
+ * Returns a representation of the stickerbook in the chosen `format`.
+ * @param {ExportStickerbookOptions[]}
+ * @returns {Promise<ExportReturn<T>>}
+ */
 export async function exportStickerbook<T extends ExportFormat>({
   canvas,
   backgrounds,

src/lib/helpers/patchSticker.ts

@@ -15,16 +15,17 @@ type PatchStickerOptions = {
     }
 )
 
-const PROPS = ["position", "scale", "rotation"] as const
-
-export type PatchStickerProps = (typeof PROPS)[number]
-
+/**
+ * Returns a copy of the provided `stickers` array with the updated ("patched") sticker in place.
+ * @param {PatchStickerOptions}
+ * @returns {StickerItem[]}
+ */
 export function patchSticker({
   stickers,
   prop,
   value,
   id,
-}: PatchStickerOptions) {
+}: PatchStickerOptions): StickerItem[] {
   if (!stickers || !(stickers instanceof Array) || stickers.length <= 0)
     throw Error("`stickers` array is empty")
 

src/lib/helpers/reorderSticker.ts

@@ -7,12 +7,17 @@ interface ReorderStickerOptions {
   stickers: StickerItem[]
 }
 
+/**
+ * Returns a reordered copy of the provided `stickers` array.
+ * @param {ReorderStickerOptions[]}
+ * @returns {StickerItem[]}
+ */
 export function reorderSticker({
   id,
   direction = "up",
   extreme = false,
   stickers,
-}: ReorderStickerOptions) {
+}: ReorderStickerOptions): StickerItem[] {
   if (!stickers || stickers.length <= 0)
     throw Error("`stickers` array is empty")
 

src/lib/index.tsx

@@ -2,6 +2,29 @@ export { Stickerbook } from "./stickerbook"
 export { Sticker } from "./sticker"
 export { useStickerbook } from "./use-stickerbook"
 
-export * from "./helpers"
+export {
+  addSticker,
+  deleteSticker,
+  exportStickerbook,
+  patchSticker,
+  reorderSticker,
+} from "./helpers"
 
-export type * from "./types"
+export type {
+  StickerItem,
+  BackgroundItem,
+  ForegroundItem,
+  Frame,
+  StickerbookProps,
+  StickerbookContextProps,
+  ExportFormat,
+  OrderDirection,
+  OnDeleteHandler,
+  OnReorderHandler,
+  OnPositionHandler,
+  OnScaleHandler,
+  OnRotateHandler,
+  OnAddStickerHandler,
+  StickerProps,
+  UseStickerbookProps,
+} from "./types"