feat: add labels prop and label slot

.github/workflows/test.yml

@@ -17,8 +17,10 @@ jobs:
           node-version: lts/*
       - name: Install dependencies
         run: npm ci
-      - run: npm run check
-      - run: npm run test:unit -- --run
+      - name: svelte-check
+        run: npm run check
+      - name: Unit tests
+        run: npm run test -- --run
       - name: Svelte 4 e2e tests
         working-directory: e2e/svelte-4
         run: |

README.md

@@ -11,8 +11,10 @@ Product") for visual regression testing.
 - [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)
 - [Svelte 5 usage (experimental)](#svelte-5-usage-experimental)
   - [Styling `<CartesianWithRunes>` (Svelte 5)](#styling-cartesianwithrunes-svelte-5)
@@ -168,6 +170,57 @@ values you wish to test, and then renders prop combinations.
 </Cartesian>
 ```
 
+### Adding labels (Svelte 4)
+
+Use the `labels` prop to generate labels next to every component instance.
+
+```html
+    <Cartesian
+      props={props}
+      Component={Component}
+      labels />
+<!--  ^^^^^^ implied as `true` -->
+```
+
+Allowed values for the `labels` prop:
+
+- `true`: same as `'short'`.
+- `'short'`: display comma-separated values, skip objects.
+- `'long'`: display line-separated key-value pairs, represent object values as their type name.
+- `'long-with-objects'`: same as `'long'`, but with full object definitions.
+
+Default labelling behaviour can be overridden with the `label` slot.
+
+```html
+<!-- Using `label` slot prop -->
+<Cartesian
+  props={props}
+  Component={Component}
+  labels
+>
+  <div class="label-container" slot="label" let:label>
+    <span class="label">Props</span>
+    <pre class="props">{label}</pre>
+  </div>
+</Cartesian>
+
+<!--
+  Using `innerProps` slot prop.
+
+  Note: `label` prop isn't required when
+  using `innerProps` to render labels.
+-->
+<Cartesian
+  props={props}
+  Component={Component}
+>
+  <div class="label-container" slot="label" let:innerProps>
+    <span class="label">Props</span>
+    <pre class="props">{customLabel(innerProps)}</pre>
+  </div>
+</Cartesian>
+```
+
 ### Styling `<Cartesian>` (Svelte 4)
 
 `<Cartesian>` has these default CSS behaviours:
@@ -210,14 +263,23 @@ There are a few ways to override its styles:
 
 ### `<Cartesian>` props (Svelte 4)
 
-| 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.                                                          |
-| `asChild`        | `?boolean=false`                | Renders the default slot's contents. Each Cartesian's iteration will pass `innerProps` as slot props. Default value `false`.             |
-| `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. Use this alongside `asChild` to spread `innerProps` to your nested component. |
+| 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.                                                                                                                   |
+| `asChild`        | `?boolean=false`                                                                | Renders the default slot's contents. Each Cartesian's iteration will pass `innerProps` as slot props. Default value `false`. See [usage with slots](#usage-with-slots-svelte-4) for more details. |
+| `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: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)
 

e2e/svelte-4/src/lib/Button.svelte

@@ -1,11 +1,23 @@
 <script>
   export let size = "medium"
   export let variant = "primary"
+  export let disabled = false
+
+  /** @type {{ [key: string]: string } | undefined} */
+  export let definitions = undefined
 </script>
 
-<button {...$$restProps} class="{variant} {size}">
+<button {...$$restProps} {disabled} class="{variant} {size}">
   <slot name="left" />
   <slot />
+  {#if definitions}
+    <dl>
+      {#each Object.entries(definitions) as [term, definition]}
+        <dt>{term}</dt>
+        <dd>{definition}</dd>
+      {/each}
+    </dl>
+  {/if}
   <slot name="right" />
 </button>
 

e2e/svelte-4/src/lib/main.css

@@ -12,3 +12,15 @@ body {
   box-sizing: border-box;
   margin: 0;
 }
+
+h1 {
+  font-size: 1.75rem;
+}
+h2 {
+  font-size: 1.5rem;
+}
+
+h1,
+h2 {
+  margin-bottom: 0.75rem;
+}

e2e/svelte-4/src/routes/labels/+page.svelte

@@ -0,0 +1,32 @@
+<script>
+  import { Cartesian } from "svelte-cartesian"
+  import Button from "$lib/Button.svelte"
+
+  const props = {
+    props: {
+      size: ["small", "medium", "large"],
+      variant: ["primary", "secondary"],
+      disabled: [true, false],
+      definitions: [{ animals: "a holistic group of species" }],
+    },
+    Component: Button,
+  }
+</script>
+
+<h1>Labelled Cartesian</h1>
+
+<h2>Short - explicit</h2>
+
+<Cartesian {...props} labels="short">Make popcorn</Cartesian>
+
+<h2>Short - implicit</h2>
+
+<Cartesian {...props} labels>Make popcorn</Cartesian>
+
+<h2>Long</h2>
+
+<Cartesian {...props} labels="long">Make popcorn</Cartesian>
+
+<h2>Long with objects</h2>
+
+<Cartesian {...props} labels="long-with-objects">Make popcorn</Cartesian>

e2e/svelte-4/src/routes/labels/custom/+page.svelte

@@ -0,0 +1,69 @@
+<script>
+  import { Cartesian } from "svelte-cartesian"
+  import Button from "$lib/Button.svelte"
+
+  const props = {
+    props: {
+      size: ["small", "medium", "large"],
+      variant: ["primary", "secondary"],
+      disabled: [true, false],
+      definitions: [{ animals: "a holistic group of species" }],
+    },
+    Component: Button,
+  }
+
+  /**
+   * @param {Record<string, any>} innerProps
+   */
+  function customLabel(innerProps) {
+    return Object.entries(innerProps)
+      .map(([key, value]) => {
+        let refinedValue = value
+
+        if (typeof value === "object") {
+          refinedValue = JSON.stringify(value)
+        } else if (typeof value !== "string" && typeof value !== "number") {
+          refinedValue = typeof value
+        }
+
+        return `${key}: ${refinedValue}`
+      })
+      .join("\n")
+  }
+</script>
+
+<h2>Custom label, string value</h2>
+
+<Cartesian {...props} labels="long-with-objects">
+  Make popcorn
+  <div class="label-container" slot="label" let:label>
+    <span class="label">Props</span>
+    <pre class="props">{label}</pre>
+  </div>
+</Cartesian>
+
+<h2>Custom label, object value</h2>
+
+<Cartesian {...props}>
+  Make popcorn
+  <div class="label-container" slot="label" let:innerProps>
+    <span class="label">Props</span>
+    <pre class="props">{customLabel(innerProps)}</pre>
+  </div>
+</Cartesian>
+
+<style>
+  .label-container {
+    border: 1px solid black;
+    border-radius: 3px;
+    padding: 0.5rem;
+    margin-top: 0.5rem;
+  }
+  .label {
+    font-size: 1.25rem;
+    font-weight: 600;
+  }
+  .props {
+    color: crimson;
+  }
+</style>

e2e/svelte-4/src/routes/labels/dark/+page.svelte

@@ -0,0 +1,12 @@
+<script>
+  import Page from "../+page.svelte"
+</script>
+
+<Page />
+
+<style>
+  :global(body) {
+    background-color: #000;
+    color: #fff;
+  }
+</style>

e2e/svelte-4/tests/tests.spec.js

@@ -2,21 +2,30 @@ import { test, expect } from '@playwright/test'
 
 test('default slot', async ({ page }) => {
   await page.goto('localhost:4173/')
-
-  // Expect a title "to contain" a substring.
   await expect(page).toHaveScreenshot()
 })
 
 test('named slots asChild', async ({ page }) => {
   await page.goto('localhost:4173/named-slots')
-
-  // Expect a title "to contain" a substring.
   await expect(page).toHaveScreenshot()
 })
 
 test('custom styles', async ({ page }) => {
   await page.goto('localhost:4173/custom-styles')
-
-  // Expect a title "to contain" a substring.
   await expect(page).toHaveScreenshot()
 })
+
+test('short and long labels', async ({ page }) => {
+  await page.goto('localhost:4173/labels')
+  await expect(page).toHaveScreenshot({ fullPage: true })
+})
+
+test('short and long labels - dark mode', async ({ page }) => {
+  await page.goto('localhost:4173/labels/dark')
+  await expect(page).toHaveScreenshot({ fullPage: true })
+})
+
+test('slotted labels', async ({ page }) => {
+  await page.goto('localhost:4173/labels/custom')
+  await expect(page).toHaveScreenshot({ fullPage: true })
+})

eslint.config.js

@@ -5,5 +5,11 @@ const compat = new FlatCompat()
 export default [
   // standard compatibility
   ...compat.extends('eslint-config-standard'),
-  ...eslintPluginSvelte.configs['flat/recommended']
+  ...eslintPluginSvelte.configs['flat/recommended'],
+  {
+    rules: {
+      'no-multi-str': 0,
+      'operator-linebreak': ['error', 'before']
+    }
+  }
 ]

jsconfig.json

@@ -9,6 +9,7 @@
     "sourceMap": true,
     "strict": true,
     "module": "ESNext",
+    "lib": ["ESNext"],
     "moduleResolution": "Bundler"
   },
   "exclude": ["e2e/**"]