Skip to content

Commit e282a7f

Browse files
janoshjanosh
committed
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
1 parent 36d9e77 commit e282a7f

File tree

5 files changed

+114
-31
lines changed

5 files changed

+114
-31
lines changed

‎readme.md

Lines changed: 82 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
[![NPM version](https://img.shields.io/npm/v/svelte-bricks?color=blue&logo=NPM)](https://npmjs.com/package/svelte-bricks)
1212
[![Netlify Status](https://api.netlify.com/api/v1/badges/c3213069-e3cc-45ef-a446-b2358b9a35fb/deploy-status)](https://app.netlify.com/sites/svelte-bricks/deploys)
1313
[![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)
14-
[![Open in StackBlitz](https://img.shields.io/badge/Open%20in-StackBlitz-darkblue?logo=pytorchlightning)](https://stackblitz.com/github/janosh/svelte-bricks)
14+
[![Open in StackBlitz](https://img.shields.io/badge/Open%20in-StackBlitz-darkblue?logo=stackblitz)](https://stackblitz.com/github/janosh/svelte-bricks)
1515

1616
</h4>
1717

@@ -67,19 +67,87 @@ h)
6767

6868
Additional optional props are:
6969

70-
- `items: (string | number | object)[]`: required
71-
- `minColWidth: number = 330` (in `px`)
72-
- `maxColWidth: number = 500` (in `px`)
73-
- `gap: number = 20` (in `px`)
74-
- `masonryWidth: number = 0`: Bound to the masonry `div`s width (in `px`).
75-
- `masonryHeight: number = 0`: Bound to the masonry `div`s height (in `px`).
76-
- `idKey: string = 'id'`: Name of the attribute to use as identifier if items are objects.
77-
- `getId: (item) => string | number`: Custom function that maps masonry items to unique IDs.
78-
- `animate: boolean = true`: Whether to [FLIP-animate](https://svelte.dev/tutorial/animate) masonry items when viewport resizing or other events cause `items` to rearrange.
79-
- `style: string = ''`: Inline styles that will be applied to the top-level `div.masonry`.
80-
- `duration: number = 200`: Transition duration in milli seconds when masonry items are rearranged or added/removed. Set to 0 to disable transitions.
81-
- `class: string = ''`: Applies to the outer `div` wrapping all masonry columns. For use with CSS frameworks like Tailwind.
82-
- `columnClass: string = ''`: Applies to each column `div`.
70+
1. ```ts
71+
animate: boolean = true
72+
```
73+
74+
Whether to [FLIP-animate](https://svelte.dev/tutorial/animate) masonry items when viewport resizing or other events cause `items` to rearrange.
75+
76+
1. ```ts
77+
class: string = ''
78+
```
79+
80+
Applies to the outer `div` wrapping all masonry columns. For use with CSS frameworks like Tailwind.
81+
82+
1. ```ts
83+
columnClass: string = ''
84+
```
85+
86+
Applies to each column `div`.
87+
88+
1. ```ts
89+
duration: number = 200
90+
```
91+
92+
Transition duration in milli seconds when masonry items are rearranged or added/removed. Set to 0 to disable transitions.
93+
94+
1. ```ts
95+
gap: number = 20
96+
```
97+
98+
Gap between columns and items within each column in `px`.
99+
100+
1. ```ts
101+
getId: (Item) => string | number = (item: Item) => {
102+
if (typeof item === `number`) return item
103+
if (typeof item === `string`) return item
104+
return (item as Record<string, unknown>)[idKey]
105+
}
106+
```
107+
108+
Custom function that maps masonry items to unique IDs of type `string` or `number`.
109+
110+
1. ```ts
111+
idKey: string = 'id'
112+
```
113+
114+
Name of the attribute to use as identifier if items are objects.
115+
116+
1. ```ts
117+
items: (string | number | object)[]
118+
```
119+
120+
required
121+
122+
1. ```ts
123+
masonryHeight: number = 0
124+
```
125+
126+
The masonry `div`s height in `px`.
127+
128+
1. ```ts
129+
masonryWidth: number = 0
130+
```
131+
132+
The masonry `div`s width in `px`.
133+
134+
1. ```ts
135+
maxColWidth: number = 500
136+
```
137+
138+
Maximum column width in `px`.
139+
140+
1. ```ts
141+
minColWidth: number = 330
142+
```
143+
144+
Minimum column width in `px`.
145+
146+
1. ```ts
147+
style: string = ''
148+
```
149+
150+
Inline styles that will be applied to the top-level `div.masonry`.
83151

84152
## Styling
85153

‎src/components/Slider.svelte

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
<script lang="ts">
2-
export let value: number, label: string, min: number, max: number
2+
export let value: number
3+
export let label: string
4+
export let min: number
5+
export let max: number
36
</script>
47

58
<label>

‎src/lib/Masonry.svelte

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -2,26 +2,25 @@
22
import { flip } from 'svelte/animate'
33
import { fade } from 'svelte/transition'
44
5-
export let items: Item[]
6-
export let minColWidth = 330
7-
export let maxColWidth = 500
8-
export let gap = 20
9-
export let masonryWidth = 0
10-
export let masonryHeight = 0
115
export let animate = true
12-
export let style = ``
13-
export let duration = 200
14-
156
export { className as class }
167
export let columnClass = ``
8+
export let duration = 200
9+
export let gap = 20
1710
// On non-primitive types, we need a property to tell masonry items apart. This component
1811
// hard-codes the name of this property to 'id'. See https://svelte.dev/tutorial/keyed-each-blocks.
19-
export let idKey = `id`
2012
export let getId = (item: Item) => {
21-
if (typeof item === `string`) return item
2213
if (typeof item === `number`) return item
14+
if (typeof item === `string`) return item
2315
return (item as Record<string, unknown>)[idKey]
2416
}
17+
export let idKey = `id`
18+
export let items: Item[]
19+
export let masonryHeight = 0
20+
export let masonryWidth = 0
21+
export let maxColWidth = 500
22+
export let minColWidth = 330
23+
export let style = ``
2524
2625
type Item = $$Generic
2726
let className = ``

‎tests/readme.test.ts

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,28 @@
1+
import Masonry from '$lib'
12
import { readFileSync } from 'fs'
23
import { expect, test } from 'vitest'
3-
import Masonry from '../src/lib'
44

5-
test(`readme documents all props`, () => {
6-
const readme = readFileSync(`readme.md`, `utf8`)
5+
const readme = readFileSync(`readme.md`, `utf8`)
76

7+
test(`readme documents all props and their correct types and defaults`, () => {
88
const instance = new Masonry({
99
target: document.body,
1010
props: { items: [] },
1111
})
12+
const { props, ctx } = instance.$$
1213

13-
for (const prop of Object.keys(instance.$$.props)) {
14-
expect(readme).to.contain(`- \`${prop}: `)
14+
for (const [prop, ctx_idx] of Object.entries(props)) {
15+
let default_val = ctx[ctx_idx as number]
16+
const type: string = typeof default_val
17+
18+
if (type === `string`) default_val = `'${default_val}'`
19+
20+
if ([`string`, `number`, `boolean`].includes(type)) {
21+
const expected = `1. \`\`\`ts\n ${prop}: ${type} = ${default_val}\n \`\`\``
22+
23+
expect(readme).to.contain(expected)
24+
} else {
25+
expect(readme).to.contain(`1. \`\`\`ts\n ${prop}: `)
26+
}
1527
}
1628
})

‎tsconfig.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
{
2+
"extends": "./.svelte-kit/tsconfig.json",
23
"compilerOptions": {
34
"strict": true,
45
"module": "esnext",

0 commit comments

Comments
 (0)