From 55238e37d8c74dc9692ee23f4225b697e4d96ec0 Mon Sep 17 00:00:00 2001
From: Enrico Sacchetti <enrico@theetrain.ca>
Date: Wed, 4 Sep 2024 15:32:43 -0400
Subject: [PATCH] docs: simplify readme

---
 README-svelte-5.md |  42 +++++++++++
 README.md          | 176 +++++++++++++++------------------------------
 2 files changed, 100 insertions(+), 118 deletions(-)
 create mode 100644 README-svelte-5.md

diff --git a/README-svelte-5.md b/README-svelte-5.md
new file mode 100644
index 0000000..1308477
--- /dev/null
+++ b/README-svelte-5.md
@@ -0,0 +1,42 @@
+## Svelte 5 usage (experimental)
+
+> [!WARNING]
+> This component is based on the release candidate of Svelte 5 and is considered
+> unstable. Any breaking changes will not be properly indicated in
+> `svelte-cartesian` releases at this time, but there are no planned changes.
+
+1. Install package
+
+   ```bash
+   npm install -D svelte-cartesian
+   ```
+
+2. Add component to your page.
+
+   ```html
+   <script>
+     import Button from "./Button.svelte"
+     import { CartesianWithRunes as Cartesian } from "svelte-cartesian"
+   </script>
+
+   {#snippet children()} Click me {/snippet} <Cartesian Component={Button}
+   props={{ variant: ['primary', 'secondary'], size: ['medium', 'large'],
+   children: [children] }} />
+   ```
+
+3. Pass props with array of potential values, including an explicit `undefined`
+   where applicable. Ensure snippets are passed in as props and defined within
+   the markup of the page using `<CartesianWithRunes>`.
+
+### Styling `<CartesianWithRunes>`
+
+Styling `<CartesianWithRunes>` is done in the exact same way as with [`<Cartesian>`](./README.md#styling-cartesian).
+
+### `<CartesianWithRunes>` props
+
+| prop            | type                            | description                                                                     |
+| --------------- | ------------------------------- | ------------------------------------------------------------------------------- |
+| `Component`     | `ComponentType`                 | **Required**: A Svelte component.                                               |
+| `props`         | `Record<string, any[]>`         | **Required**: An object containing prop names and an array of potential values. |
+| `unstyled`      | `?boolean=false`                | Disable built-in CSS.                                                           |
+| `divAttributes` | `?SvelteHTMLElements["div"]={}` | Attributes to be spread onto the wrapping `<div>` element.                      |
diff --git a/README.md b/README.md
index ec31cb5..8573256 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,29 @@
 # Svelte Cartesian
 
-A single component that helps render prop combinations (the "Cartesian
-Product") for visual regression testing.
+A single component that helps render prop combinations. It can be used with visual regression test software such as Playwright
+or Storybook (see [examples](#examples)).
+
+Its name comes from "Cartesian Product" in which an intersection of two
+or more arrays form a matrix, such as:
+
+```
+[a, b] * [x, y] --> [[a, x], [a, y], [b, x], [b, y]]
+```
 
 <img src="https://raw.githubusercontent.com/theetrain/svelte-cartesian/main/demo.jpg" alt="Cartesian demonstration featuring a 4 x 3 x 2 combination." />
 
 - [Why](#why)
   - [Before using `svelte-cartesian`](#before-using-svelte-cartesian)
   - [After using `svelte-cartesian`](#after-using-svelte-cartesian)
-- [Svelte 4 usage](#svelte-4-usage)
-  - [Basic usage (Svelte 4)](#basic-usage-svelte-4)
-  - [Usage with slots (Svelte 4)](#usage-with-slots-svelte-4)
-  - [Adding labels (Svelte 4)](#adding-labels-svelte-4)
-  - [Styling `<Cartesian>` (Svelte 4)](#styling-cartesian-svelte-4)
-  - [`<Cartesian>` props (Svelte 4)](#cartesian-props-svelte-4)
-  - [`<Cartesian>` slots (Svelte 4)](#cartesian-slots-svelte-4)
-  - [Examples (Svelte 4)](#examples-svelte-4)
+- [Setup](#setup)
+- [Basic usage](#basic-usage)
+- [Usage with slots](#usage-with-slots)
+  - [Available slots](#available-slots)
+- [Adding labels](#adding-labels)
+- [Styling `<Cartesian>`](#styling-cartesian)
+- [`<Cartesian>` props](#cartesian-props)
+- [Examples](#examples)
 - [Svelte 5 usage (experimental)](#svelte-5-usage-experimental)
-  - [Styling `<CartesianWithRunes>` (Svelte 5)](#styling-cartesianwithrunes-svelte-5)
-  - [`<CartesianWithRunes>` props (Svelte 5)](#cartesianwithrunes-props-svelte-5)
 - [Project roadmap](#project-roadmap)
   - [Goals](#goals)
   - [Non-goals](#non-goals)
@@ -44,27 +49,26 @@ many combinations of a component requires nested `{#each}` loops and some style
 boilerplate. `svelte-cartesian` solves this in one component that accepts prop
 values you wish to test, and then renders prop combinations.
 
-<details>
-<summary>Before and after using <code>svelte-cartesian</code></summary>
-
 ### Before using `svelte-cartesian`
 
+<!-- prettier-ignore-start -->
 ```html
 <script>
-  import { Button } from './Button.svelte'
+  import { Button } from "./Button.svelte"
 </script>
 
 <!-- This nests deeper with every additional prop -->
 {#each ['primary', 'secondary'] as variant}
   {#each ['small', 'medium', 'large'] as size}
     {#each ['main', 'common', 'ghost'] as prominence}
-      <Button {size} {variant} {prominence}>
+      <button {size} {variant} {prominence}>
         Dispense popcorn
-      </Button>
+      </button>
     {/each}
   {/each}
 {/each}
 ```
+<!-- prettier-ignore-end -->
 
 ### After using `svelte-cartesian`
 
@@ -86,28 +90,26 @@ values you wish to test, and then renders prop combinations.
 </Cartesian>
 ```
 
-</details>
-
-## Svelte 4 usage
+## Setup
 
 1. Install package
 
-    ```bash
-    npm install -D svelte-cartesian
-    ```
+   ```bash
+   npm install -D svelte-cartesian
+   ```
 
 2. Add component to your page.
 
-    ```html
-    <script>
-      import { Cartesian } from 'svelte-cartesian'
-    </script>
-    ```
+   ```html
+   <script>
+     import { Cartesian } from "svelte-cartesian"
+   </script>
+   ```
 
 3. Pass props with array of potential values, including an explicit `undefined`
    where applicable.
 
-### Basic usage (Svelte 4)
+## Basic usage
 
 - Pass a component to the `Component` prop.
 - Pass an object to `props` containing possible prop keys for your passed-in
@@ -130,7 +132,7 @@ values you wish to test, and then renders prop combinations.
 </Cartesian>
 ```
 
-### Usage with slots (Svelte 4)
+## Usage with slots
 
 - Pass your component into the default slot.
 - Spread the `innerProps` slot prop to your component, which will render a
@@ -140,45 +142,45 @@ values you wish to test, and then renders prop combinations.
 
 ```html
 <script>
-  import Button from './Button.svelte'
-  import { Cartesian } from 'svelte-cartesian'
+  import Button from "./Button.svelte"
+  import { Cartesian } from "svelte-cartesian"
 
   const props = {
     Component: Button,
     props: {
-      variant: ['primary', 'secondary'],
-      size: ['medium', 'large']
-    }
+      variant: ["primary", "secondary"],
+      size: ["medium", "large"],
+    },
   }
 </script>
 
 <!-- Left slot + default slot -->
 <Cartesian {...props} let:innerProps>
-  <Button {...innerProps}>
-    <svelte:fragment slot="left">
-      Left contents
-    </svelte:fragment>
+  <button {...innerProps}>
+    <svelte:fragment slot="left"> Left contents </svelte:fragment>
     Click me
-  </Button>
+  </button>
 </Cartesian>
 
 <!-- Default slot on its own -->
 <Cartesian {...props} let:innerProps>
-  <Button {...innerProps}>
-    Click me
-  </Button>
+  <button {...innerProps}>Click me</button>
 </Cartesian>
 ```
 
-### Adding labels (Svelte 4)
+### Available slots
+
+| slot name | slot props                    | description                                                                                                                                                                                                                              |
+| --------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _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. |
+| `label`   | `let:label`, `let:innerProps` | Provide your own label, styles, and logic instead of the default provided label.                                                                                                                                                         |
+
+## Adding labels
 
 Use the `labels` prop to generate labels next to every component instance.
 
 ```html
-    <Cartesian
-      props={props}
-      Component={Component}
-      labels />
+<Cartesian props="{props}" Component="{Component}" labels />
 <!--  ^^^^^^ implied as `true` -->
 ```
 
@@ -193,11 +195,7 @@ Default labelling behaviour can be overridden with the `label` slot.
 
 ```html
 <!-- Using `label` slot prop -->
-<Cartesian
-  props={props}
-  Component={Component}
-  labels
->
+<Cartesian props="{props}" Component="{Component}" labels>
   <div class="label-container" slot="label" let:label>
     <span class="label">Props</span>
     <pre class="props">{label}</pre>
@@ -210,10 +208,7 @@ Default labelling behaviour can be overridden with the `label` slot.
   Note: `label` prop isn't required when
   using `innerProps` to render labels.
 -->
-<Cartesian
-  props={props}
-  Component={Component}
->
+<Cartesian props="{props}" Component="{Component}">
   <div class="label-container" slot="label" let:innerProps>
     <span class="label">Props</span>
     <pre class="props">{customLabel(innerProps)}</pre>
@@ -221,7 +216,7 @@ Default labelling behaviour can be overridden with the `label` slot.
 </Cartesian>
 ```
 
-### Styling `<Cartesian>` (Svelte 4)
+## Styling `<Cartesian>`
 
 `<Cartesian>` has these default CSS behaviours:
 
@@ -261,7 +256,7 @@ There are a few ways to override its styles:
 </Cartesian>
 ```
 
-### `<Cartesian>` props (Svelte 4)
+## `<Cartesian>` props
 
 | prop             | type                                                                            | description                                                                                                                                                                                       |
 | ---------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -271,71 +266,16 @@ There are a few ways to override its styles:
 | `labels`         | `?(undefined \| boolean \| 'short' \| 'long' \| 'long-with-objects')=undefined` | Generate labels under every iteration. See [adding labels](#adding-labels-svelte-4) for detailed usage.                                                                                           |
 | `unstyled`       | `?boolean=false`                                                                | Disable built-in CSS.                                                                                                                                                                             |
 | `divAttributes`  | `?SvelteHTMLElements["div"]={}`                                                 | Attributes to be spread onto the wrapping `<div>` element.                                                                                                                                        |
-| `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.                                    |
+| `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.                                    |
 | `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.                                                        |
 
-### `<Cartesian>` slots (Svelte 4)
-
-| slot name | slot props                    | description                                                                                                                                                                                                                              |
-| --------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| *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. |
-| `label`   | `let:label`, `let:innerProps` | Provide your own label, styles, and logic instead of the default provided label.                                                                                                                                                         |
-
-### Examples (Svelte 4)
+## Examples
 
 See more examples in [end to end tests](./e2e/svelte-4/src/routes/).
 
 ## Svelte 5 usage (experimental)
 
->[!WARNING]
->This component is based on the release candidate of Svelte 5 and is considered
->unstable. Any breaking changes will not be properly indicated in
->`svelte-cartesian` releases at this time, but there are no planned changes.
-
-1. Install package
-
-    ```bash
-    npm install -D svelte-cartesian
-    ```
-
-2. Add component to your page.
-
-    ```html
-    <script>
-      import Button from './Button.svelte'
-      import { CartesianWithRunes as Cartesian } from 'svelte-cartesian'
-    </script>
-
-    {#snippet children()}
-      Click me
-    {/snippet}
-
-    <Cartesian
-      Component={Button}
-      props={{
-        variant: ['primary', 'secondary'],
-        size: ['medium', 'large'],
-        children: [children]
-      }}
-    />
-    ```
-
-3. Pass props with array of potential values, including an explicit `undefined`
-   where applicable. Ensure snippets are passed in as props and defined within
-   the markup of the page using `<CartesianWithRunes>`.
-
-### Styling `<CartesianWithRunes>` (Svelte 5)
-
-Styling `<CartesianWithRunes>` is done in the exact same way as with [`<Cartesian>`](#styling-cartesian-svelte-4).
-
-### `<CartesianWithRunes>` props (Svelte 5)
-
-| prop            | type                            | description                                                                     |
-| --------------- | ------------------------------- | ------------------------------------------------------------------------------- |
-| `Component`     | `ComponentType`                 | **Required**: A Svelte component.                                               |
-| `props`         | `Record<string, any[]>`         | **Required**: An object containing prop names and an array of potential values. |
-| `unstyled`      | `?boolean=false`                | Disable built-in CSS.                                                           |
-| `divAttributes` | `?SvelteHTMLElements["div"]={}` | Attributes to be spread onto the wrapping `<div>` element.                      |
+See [Svelte 5 README](./README-svelte-5.md).
 
 ## Project roadmap