From e282a7fb4bbd8fae33abc1747757e9c1cf1b06b6 Mon Sep 17 00:00:00 2001
From: Janosh Riebesell <janosh.riebesell@gmail.com>
Date: Tue, 13 Sep 2022 15:26:03 -0700
Subject: [PATCH] use code fences to document props in readme

improve readme test: now includes checking readme lists correct type and default value for primitive-type props
---
 readme.md                    | 96 ++++++++++++++++++++++++++++++------
 src/components/Slider.svelte |  5 +-
 src/lib/Masonry.svelte       | 21 ++++----
 tests/readme.test.ts         | 22 +++++++--
 tsconfig.json                |  1 +
 5 files changed, 114 insertions(+), 31 deletions(-)

diff --git a/readme.md b/readme.md
index 5a53ff7..25a5882 100644
--- a/readme.md
+++ b/readme.md
@@ -11,7 +11,7 @@
 [![NPM version](https://img.shields.io/npm/v/svelte-bricks?color=blue&logo=NPM)](https://npmjs.com/package/svelte-bricks)
 [![Netlify Status](https://api.netlify.com/api/v1/badges/c3213069-e3cc-45ef-a446-b2358b9a35fb/deploy-status)](https://app.netlify.com/sites/svelte-bricks/deploys)
 [![pre-commit.ci status](https://results.pre-commit.ci/badge/github/janosh/svelte-bricks/main.svg)](https://results.pre-commit.ci/latest/github/janosh/svelte-bricks/main)
-[![Open in StackBlitz](https://img.shields.io/badge/Open%20in-StackBlitz-darkblue?logo=pytorchlightning)](https://stackblitz.com/github/janosh/svelte-bricks)
+[![Open in StackBlitz](https://img.shields.io/badge/Open%20in-StackBlitz-darkblue?logo=stackblitz)](https://stackblitz.com/github/janosh/svelte-bricks)
 
 </h4>
 
@@ -67,19 +67,87 @@ h)
 
 Additional optional props are:
 
-- `items: (string | number | object)[]`: required
-- `minColWidth: number = 330` (in `px`)
-- `maxColWidth: number = 500` (in `px`)
-- `gap: number = 20` (in `px`)
-- `masonryWidth: number = 0`: Bound to the masonry `div`s width (in `px`).
-- `masonryHeight: number = 0`: Bound to the masonry `div`s height (in `px`).
-- `idKey: string = 'id'`: Name of the attribute to use as identifier if items are objects.
-- `getId: (item) => string | number`: Custom function that maps masonry items to unique IDs.
-- `animate: boolean = true`: Whether to [FLIP-animate](https://svelte.dev/tutorial/animate) masonry items when viewport resizing or other events cause `items` to rearrange.
-- `style: string = ''`: Inline styles that will be applied to the top-level `div.masonry`.
-- `duration: number = 200`: Transition duration in milli seconds when masonry items are rearranged or added/removed. Set to 0 to disable transitions.
-- `class: string = ''`: Applies to the outer `div` wrapping all masonry columns. For use with CSS frameworks like Tailwind.
-- `columnClass: string = ''`: Applies to each column `div`.
+1. ```ts
+   animate: boolean = true
+   ```
+
+   Whether to [FLIP-animate](https://svelte.dev/tutorial/animate) masonry items when viewport resizing or other events cause `items` to rearrange.
+
+1. ```ts
+   class: string = ''
+   ```
+
+   Applies to the outer `div` wrapping all masonry columns. For use with CSS frameworks like Tailwind.
+
+1. ```ts
+   columnClass: string = ''
+   ```
+
+   Applies to each column `div`.
+
+1. ```ts
+   duration: number = 200
+   ```
+
+   Transition duration in milli seconds when masonry items are rearranged or added/removed. Set to 0 to disable transitions.
+
+1. ```ts
+   gap: number = 20
+   ```
+
+   Gap between columns and items within each column in `px`.
+
+1. ```ts
+   getId: (Item) => string | number = (item: Item) => {
+     if (typeof item === `number`) return item
+     if (typeof item === `string`) return item
+     return (item as Record<string, unknown>)[idKey]
+   }
+   ```
+
+   Custom function that maps masonry items to unique IDs of type `string` or `number`.
+
+1. ```ts
+   idKey: string = 'id'
+   ```
+
+   Name of the attribute to use as identifier if items are objects.
+
+1. ```ts
+   items: (string | number | object)[]
+   ```
+
+   required
+
+1. ```ts
+   masonryHeight: number = 0
+   ```
+
+   The masonry `div`s height in `px`.
+
+1. ```ts
+   masonryWidth: number = 0
+   ```
+
+   The masonry `div`s width in `px`.
+
+1. ```ts
+   maxColWidth: number = 500
+   ```
+
+   Maximum column width in `px`.
+
+1. ```ts
+   minColWidth: number = 330
+   ```
+
+   Minimum column width in `px`.
+
+1. ```ts
+   style: string = ''
+   ```
+
+   Inline styles that will be applied to the top-level `div.masonry`.
 
 ## Styling
 
diff --git a/src/components/Slider.svelte b/src/components/Slider.svelte
index cc16a1e..b232b92 100644
--- a/src/components/Slider.svelte
+++ b/src/components/Slider.svelte
@@ -1,5 +1,8 @@
 <script lang="ts">
-  export let value: number, label: string, min: number, max: number
+  export let value: number
+  export let label: string
+  export let min: number
+  export let max: number
 </script>
 
 <label>
diff --git a/src/lib/Masonry.svelte b/src/lib/Masonry.svelte
index 40d8e84..cb69015 100644
--- a/src/lib/Masonry.svelte
+++ b/src/lib/Masonry.svelte
@@ -2,26 +2,25 @@
   import { flip } from 'svelte/animate'
   import { fade } from 'svelte/transition'
 
-  export let items: Item[]
-  export let minColWidth = 330
-  export let maxColWidth = 500
-  export let gap = 20
-  export let masonryWidth = 0
-  export let masonryHeight = 0
   export let animate = true
-  export let style = ``
-  export let duration = 200
-
   export { className as class }
   export let columnClass = ``
+  export let duration = 200
+  export let gap = 20
   // On non-primitive types, we need a property to tell masonry items apart. This component
   // hard-codes the name of this property to 'id'. See https://svelte.dev/tutorial/keyed-each-blocks.
-  export let idKey = `id`
   export let getId = (item: Item) => {
-    if (typeof item === `string`) return item
     if (typeof item === `number`) return item
+    if (typeof item === `string`) return item
     return (item as Record<string, unknown>)[idKey]
   }
+  export let idKey = `id`
+  export let items: Item[]
+  export let masonryHeight = 0
+  export let masonryWidth = 0
+  export let maxColWidth = 500
+  export let minColWidth = 330
+  export let style = ``
 
   type Item = $$Generic
   let className = ``
diff --git a/tests/readme.test.ts b/tests/readme.test.ts
index daf2df2..b6ebff1 100644
--- a/tests/readme.test.ts
+++ b/tests/readme.test.ts
@@ -1,16 +1,28 @@
+import Masonry from '$lib'
 import { readFileSync } from 'fs'
 import { expect, test } from 'vitest'
-import Masonry from '../src/lib'
 
-test(`readme documents all props`, () => {
-  const readme = readFileSync(`readme.md`, `utf8`)
+const readme = readFileSync(`readme.md`, `utf8`)
 
+test(`readme documents all props and their correct types and defaults`, () => {
   const instance = new Masonry({
     target: document.body,
     props: { items: [] },
   })
+  const { props, ctx } = instance.$$
 
-  for (const prop of Object.keys(instance.$$.props)) {
-    expect(readme).to.contain(`- \`${prop}: `)
+  for (const [prop, ctx_idx] of Object.entries(props)) {
+    let default_val = ctx[ctx_idx as number]
+    const type: string = typeof default_val
+
+    if (type === `string`) default_val = `'${default_val}'`
+
+    if ([`string`, `number`, `boolean`].includes(type)) {
+      const expected = `1. \`\`\`ts\n   ${prop}: ${type} = ${default_val}\n   \`\`\``
+
+      expect(readme).to.contain(expected)
+    } else {
+      expect(readme).to.contain(`1. \`\`\`ts\n   ${prop}: `)
+    }
   }
 })
diff --git a/tsconfig.json b/tsconfig.json
index ce6dcae..637f267 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,4 +1,5 @@
 {
+  "extends": "./.svelte-kit/tsconfig.json",
   "compilerOptions": {
     "strict": true,
     "module": "esnext",