Skip to content

Commit 9760894

Browse files
theetraintheetrain
committed
docs: simplify readme
1 parent 063ff16 commit 9760894

File tree

2 files changed

+150
-110
lines changed

2 files changed

+150
-110
lines changed

‎README-svelte-5.md

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
## Svelte 5 usage (experimental)
2+
3+
> [!WARNING]
4+
> This component is based on the release candidate of Svelte 5 and is considered
5+
> unstable. Any breaking changes will not be properly indicated in
6+
> `svelte-cartesian` releases at this time, but there are no planned changes.
7+
8+
1. Install package
9+
10+
```bash
11+
npm install -D svelte-cartesian
12+
```
13+
14+
2. Add component to your page.
15+
16+
```html
17+
<script>
18+
import Button from "./Button.svelte"
19+
import { CartesianWithRunes as Cartesian } from "svelte-cartesian"
20+
</script>
21+
22+
{#snippet children()} Click me {/snippet} <Cartesian Component={Button}
23+
props={{ variant: ['primary', 'secondary'], size: ['medium', 'large'],
24+
children: [children] }} />
25+
```
26+
27+
3. Pass props with array of potential values, including an explicit `undefined`
28+
where applicable. Ensure snippets are passed in as props and defined within
29+
the markup of the page using `<CartesianWithRunes>`.
30+
31+
### Styling `<CartesianWithRunes>`
32+
33+
Styling `<CartesianWithRunes>` is done in the exact same way as with [`<Cartesian>`](./README.md#styling-cartesian).
34+
35+
### `<CartesianWithRunes>` props
36+
37+
| prop | type | description |
38+
| --------------- | ------------------------------- | ------------------------------------------------------------------------------- |
39+
| `Component` | `ComponentType` | **Required**: A Svelte component. |
40+
| `props` | `Record<string, any[]>` | **Required**: An object containing prop names and an array of potential values. |
41+
| `unstyled` | `?boolean=false` | Disable built-in CSS. |
42+
| `divAttributes` | `?SvelteHTMLElements["div"]={}` | Attributes to be spread onto the wrapping `<div>` element. |

‎README.md

+108-110
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,31 @@
11
# Svelte Cartesian
22

3-
A single component that helps render prop combinations (the "Cartesian
4-
Product") for visual regression testing.
3+
A single component that helps render prop combinations. It can be used with visual regression test software such as [Playwright](https://playwright.dev/)
4+
or [Storybook](https://storybook.js.org/) (see [examples](#examples)).
5+
6+
Its name comes from "Cartesian Product" in which an intersection of two
7+
or more arrays form a matrix, such as:
8+
9+
```
10+
[a, b] * [x, y] --> [[a, x], [a, y], [b, x], [b, y]]
11+
```
512

613
<img src="https://raw.githubusercontent.com/theetrain/svelte-cartesian/main/demo.jpg" alt="Cartesian demonstration featuring a 4 x 3 x 2 combination." />
714

815
- [Why](#why)
916
- [Before using `svelte-cartesian`](#before-using-svelte-cartesian)
1017
- [After using `svelte-cartesian`](#after-using-svelte-cartesian)
11-
- [Svelte 4 usage](#svelte-4-usage)
12-
- [Basic usage (Svelte 4)](#basic-usage-svelte-4)
13-
- [Usage with slots (Svelte 4)](#usage-with-slots-svelte-4)
14-
- [Adding labels (Svelte 4)](#adding-labels-svelte-4)
15-
- [Styling `<Cartesian>` (Svelte 4)](#styling-cartesian-svelte-4)
16-
- [`<Cartesian>` props (Svelte 4)](#cartesian-props-svelte-4)
17-
- [`<Cartesian>` slots (Svelte 4)](#cartesian-slots-svelte-4)
18-
- [Examples (Svelte 4)](#examples-svelte-4)
18+
- [Setup](#setup)
19+
- [Basic usage](#basic-usage)
20+
- [Usage with slots](#usage-with-slots)
21+
- [Available slots](#available-slots)
22+
- [Adding labels](#adding-labels)
23+
- [Styling `<Cartesian>`](#styling-cartesian)
24+
- [`<Cartesian>` props](#cartesian-props)
25+
- [Examples](#examples)
26+
- [Usage with Playwright](#usage-with-playwright)
27+
- [Usage with Storybook](#usage-with-storybook)
1928
- [Svelte 5 usage (experimental)](#svelte-5-usage-experimental)
20-
- [Styling `<CartesianWithRunes>` (Svelte 5)](#styling-cartesianwithrunes-svelte-5)
21-
- [`<CartesianWithRunes>` props (Svelte 5)](#cartesianwithrunes-props-svelte-5)
2229
- [Project roadmap](#project-roadmap)
2330
- [Goals](#goals)
2431
- [Non-goals](#non-goals)
@@ -44,27 +51,26 @@ many combinations of a component requires nested `{#each}` loops and some style
4451
boilerplate. `svelte-cartesian` solves this in one component that accepts prop
4552
values you wish to test, and then renders prop combinations.
4653

47-
<details>
48-
<summary>Before and after using <code>svelte-cartesian</code></summary>
49-
5054
### Before using `svelte-cartesian`
5155

56+
<!-- prettier-ignore-start -->
5257
```html
5358
<script>
54-
import { Button } from './Button.svelte'
59+
import { Button } from "./Button.svelte"
5560
</script>
5661

5762
<!-- This nests deeper with every additional prop -->
5863
{#each ['primary', 'secondary'] as variant}
5964
{#each ['small', 'medium', 'large'] as size}
6065
{#each ['main', 'common', 'ghost'] as prominence}
61-
<Button {size} {variant} {prominence}>
66+
<button {size} {variant} {prominence}>
6267
Dispense popcorn
63-
</Button>
68+
</button>
6469
{/each}
6570
{/each}
6671
{/each}
6772
```
73+
<!-- prettier-ignore-end -->
6874

6975
### After using `svelte-cartesian`
7076

@@ -86,28 +92,26 @@ values you wish to test, and then renders prop combinations.
8692
</Cartesian>
8793
```
8894

89-
</details>
90-
91-
## Svelte 4 usage
95+
## Setup
9296

9397
1. Install package
9498

95-
```bash
96-
npm install -D svelte-cartesian
97-
```
99+
```bash
100+
npm install -D svelte-cartesian
101+
```
98102

99103
2. Add component to your page.
100104

101-
```html
102-
<script>
103-
import { Cartesian } from 'svelte-cartesian'
104-
</script>
105-
```
105+
```html
106+
<script>
107+
import { Cartesian } from "svelte-cartesian"
108+
</script>
109+
```
106110

107111
3. Pass props with array of potential values, including an explicit `undefined`
108112
where applicable.
109113

110-
### Basic usage (Svelte 4)
114+
## Basic usage
111115

112116
- Pass a component to the `Component` prop.
113117
- Pass an object to `props` containing possible prop keys for your passed-in
@@ -130,7 +134,7 @@ values you wish to test, and then renders prop combinations.
130134
</Cartesian>
131135
```
132136

133-
### Usage with slots (Svelte 4)
137+
## Usage with slots
134138

135139
- Pass your component into the default slot.
136140
- Spread the `innerProps` slot prop to your component, which will render a
@@ -140,45 +144,45 @@ values you wish to test, and then renders prop combinations.
140144

141145
```html
142146
<script>
143-
import Button from './Button.svelte'
144-
import { Cartesian } from 'svelte-cartesian'
147+
import Button from "./Button.svelte"
148+
import { Cartesian } from "svelte-cartesian"
145149
146150
const props = {
147151
Component: Button,
148152
props: {
149-
variant: ['primary', 'secondary'],
150-
size: ['medium', 'large']
151-
}
153+
variant: ["primary", "secondary"],
154+
size: ["medium", "large"],
155+
},
152156
}
153157
</script>
154158

155159
<!-- Left slot + default slot -->
156160
<Cartesian {...props} let:innerProps>
157-
<Button {...innerProps}>
158-
<svelte:fragment slot="left">
159-
Left contents
160-
</svelte:fragment>
161+
<button {...innerProps}>
162+
<svelte:fragment slot="left"> Left contents </svelte:fragment>
161163
Click me
162-
</Button>
164+
</button>
163165
</Cartesian>
164166

165167
<!-- Default slot on its own -->
166168
<Cartesian {...props} let:innerProps>
167-
<Button {...innerProps}>
168-
Click me
169-
</Button>
169+
<button {...innerProps}>Click me</button>
170170
</Cartesian>
171171
```
172172

173-
### Adding labels (Svelte 4)
173+
### Available slots
174+
175+
| slot name | slot props | description |
176+
| --------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
177+
| _default_ | `let:innerProps` | Default slot. Contents get passed to provided `Component`. When `asChild` is set to `true`, contents **MAY** contain provided `Component` and its respective slots; see [usage with slots](#usage-with-slots-svelte-4) for more details. |
178+
| `label` | `let:label`, `let:innerProps` | Provide your own label, styles, and logic instead of the default provided label. |
179+
180+
## Adding labels
174181

175182
Use the `labels` prop to generate labels next to every component instance.
176183

177184
```html
178-
<Cartesian
179-
props={props}
180-
Component={Component}
181-
labels />
185+
<Cartesian props="{props}" Component="{Component}" labels />
182186
<!-- ^^^^^^ implied as `true` -->
183187
```
184188

@@ -193,11 +197,7 @@ Default labelling behaviour can be overridden with the `label` slot.
193197

194198
```html
195199
<!-- Using `label` slot prop -->
196-
<Cartesian
197-
props={props}
198-
Component={Component}
199-
labels
200-
>
200+
<Cartesian props="{props}" Component="{Component}" labels>
201201
<div class="label-container" slot="label" let:label>
202202
<span class="label">Props</span>
203203
<pre class="props">{label}</pre>
@@ -210,18 +210,15 @@ Default labelling behaviour can be overridden with the `label` slot.
210210
Note: `label` prop isn't required when
211211
using `innerProps` to render labels.
212212
-->
213-
<Cartesian
214-
props={props}
215-
Component={Component}
216-
>
213+
<Cartesian props="{props}" Component="{Component}">
217214
<div class="label-container" slot="label" let:innerProps>
218215
<span class="label">Props</span>
219216
<pre class="props">{customLabel(innerProps)}</pre>
220217
</div>
221218
</Cartesian>
222219
```
223220

224-
### Styling `<Cartesian>` (Svelte 4)
221+
## Styling `<Cartesian>`
225222

226223
`<Cartesian>` has these default CSS behaviours:
227224

@@ -261,7 +258,7 @@ There are a few ways to override its styles:
261258
</Cartesian>
262259
```
263260

264-
### `<Cartesian>` props (Svelte 4)
261+
## `<Cartesian>` props
265262

266263
| prop | type | description |
267264
| ---------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -271,71 +268,72 @@ There are a few ways to override its styles:
271268
| `labels` | `?(undefined \| boolean \| 'short' \| 'long' \| 'long-with-objects')=undefined` | Generate labels under every iteration. See [adding labels](#adding-labels-svelte-4) for detailed usage. |
272269
| `unstyled` | `?boolean=false` | Disable built-in CSS. |
273270
| `divAttributes` | `?SvelteHTMLElements["div"]={}` | Attributes to be spread onto the wrapping `<div>` element. |
274-
| `let:innerProps` | `Record<string, any>` | Provides a single combination of props at every iteration to the *default* slot. Use this alongside `asChild` to spread `innerProps` to your nested component. |
271+
| `let:innerProps` | `Record<string, any>` | Provides a single combination of props at every iteration to the _default_ slot. Use this alongside `asChild` to spread `innerProps` to your nested component. |
275272
| `let:label` | `string` | Generated label for a given instance. This is provided to the `label` slot. See [adding labels](#adding-labels-svelte-4) for more details. |
276273

277-
### `<Cartesian>` slots (Svelte 4)
274+
## Examples
278275

279-
| slot name | slot props | description |
280-
| --------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
281-
| *default* | `let:innerProps` | Default slot. Contents get passed to provided `Component`. When `asChild` is set to `true`, contents **MAY** contain provided `Component` and its respective slots; see [usage with slots](#usage-with-slots-svelte-4) for more details. |
282-
| `label` | `let:label`, `let:innerProps` | Provide your own label, styles, and logic instead of the default provided label. |
276+
### Usage with Playwright
283277

284-
### Examples (Svelte 4)
278+
1. Create a page using `<Cartesian />`
279+
2. Set up a test to take a screenshot of your page.
285280

286-
See more examples in [end to end tests](./e2e/svelte-4/src/routes/).
287-
288-
## Svelte 5 usage (experimental)
281+
```js
282+
test("default slot", async ({ page }) => {
283+
await page.goto("localhost:4173/")
284+
await expect(page).toHaveScreenshot()
285+
})
286+
```
289287

290-
>[!WARNING]
291-
>This component is based on the release candidate of Svelte 5 and is considered
292-
>unstable. Any breaking changes will not be properly indicated in
293-
>`svelte-cartesian` releases at this time, but there are no planned changes.
288+
See complete Playwright examples in [end to end
289+
tests](./e2e/svelte-4/src/routes/).
294290

295-
1. Install package
291+
### Usage with Storybook
296292

297-
```bash
298-
npm install -D svelte-cartesian
299-
```
293+
1. Set up a component story.
294+
2. Import `<Cartesian />` to render prop combinations:
300295

301-
2. Add component to your page.
296+
```html
297+
<script context="module">
298+
import { Story, Template } from "@storybook/addon-svelte-csf"
299+
import { Cartesian } from "svelte-cartesian"
300+
import Switch from "./Switch.svelte"
301+
302+
export const meta = {
303+
title: "Switch",
304+
component: Switch,
305+
tags: ["autodocs"],
306+
}
307+
const props = {
308+
label: ["Active profile"],
309+
size: ["sm", "md"],
310+
toggle: ["on", "off"],
311+
buttonAttributes: [{ disabled: true }, { disabled: false }],
312+
}
313+
</script>
302314

303-
```html
304-
<script>
305-
import Button from './Button.svelte'
306-
import { CartesianWithRunes as Cartesian } from 'svelte-cartesian'
307-
</script>
308-
309-
{#snippet children()}
310-
Click me
311-
{/snippet}
312-
313-
<Cartesian
314-
Component={Button}
315-
props={{
316-
variant: ['primary', 'secondary'],
317-
size: ['medium', 'large'],
318-
children: [children]
319-
}}
320-
/>
321-
```
315+
<!-- Basic Cartesian usage -->
316+
<template>
317+
<Cartesian {props} Component="{Switch}" />
318+
</template>
322319

323-
3. Pass props with array of potential values, including an explicit `undefined`
324-
where applicable. Ensure snippets are passed in as props and defined within
325-
the markup of the page using `<CartesianWithRunes>`.
320+
<Story name="Switches" />
326321

327-
### Styling `<CartesianWithRunes>` (Svelte 5)
322+
<!--
323+
Optional, but recommended to test states
324+
-->
325+
<Story name="Switches Pressed" parameters={{ pseudo: { active: true } }} />
326+
<Story name="Switches Focused" parameters={{ pseudo: { focusVisible: true } }}
327+
/>
328+
```
328329

329-
Styling `<CartesianWithRunes>` is done in the exact same way as with [`<Cartesian>`](#styling-cartesian-svelte-4).
330+
See
331+
[storybook-addon-pseudo-states](https://github.com/chromaui/storybook-addon-pseudo-states)
332+
for more inspiration.
330333

331-
### `<CartesianWithRunes>` props (Svelte 5)
334+
## Svelte 5 usage (experimental)
332335

333-
| prop | type | description |
334-
| --------------- | ------------------------------- | ------------------------------------------------------------------------------- |
335-
| `Component` | `ComponentType` | **Required**: A Svelte component. |
336-
| `props` | `Record<string, any[]>` | **Required**: An object containing prop names and an array of potential values. |
337-
| `unstyled` | `?boolean=false` | Disable built-in CSS. |
338-
| `divAttributes` | `?SvelteHTMLElements["div"]={}` | Attributes to be spread onto the wrapping `<div>` element. |
336+
See [Svelte 5 README](./README-svelte-5.md).
339337

340338
## Project roadmap
341339

0 commit comments

Comments
 (0)