Skip to content

Commit efb94f4

Browse files
theetraintheetrain
committed
docs: add labelling guide
- Update props table - Add slots table - Adjust JSDocs for `labels` prop
1 parent 4736962 commit efb94f4

File tree

4 files changed

+85
-20
lines changed

4 files changed

+85
-20
lines changed

‎README.md

Lines changed: 70 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,10 @@ Product") for visual regression testing.
1111
- [Svelte 4 usage](#svelte-4-usage)
1212
- [Basic usage (Svelte 4)](#basic-usage-svelte-4)
1313
- [Usage with slots (Svelte 4)](#usage-with-slots-svelte-4)
14+
- [Adding labels (Svelte 4)](#adding-labels-svelte-4)
1415
- [Styling `<Cartesian>` (Svelte 4)](#styling-cartesian-svelte-4)
1516
- [`<Cartesian>` props (Svelte 4)](#cartesian-props-svelte-4)
17+
- [`<Cartesian>` slots (Svelte 4)](#cartesian-slots-svelte-4)
1618
- [Examples (Svelte 4)](#examples-svelte-4)
1719
- [Svelte 5 usage (experimental)](#svelte-5-usage-experimental)
1820
- [Styling `<CartesianWithRunes>` (Svelte 5)](#styling-cartesianwithrunes-svelte-5)
@@ -168,6 +170,57 @@ values you wish to test, and then renders prop combinations.
168170
</Cartesian>
169171
```
170172
173+
### Adding labels (Svelte 4)
174+
175+
Use the `labels` prop to generate labels next to every component instance.
176+
177+
```html
178+
<Cartesian
179+
props={props}
180+
Component={Component}
181+
labels />
182+
<!-- ^^^^^^ implied as `true` -->
183+
```
184+
185+
Allowed values for the `labels` prop:
186+
187+
- `true`: same as `'short'`.
188+
- `'short'`: display comma-separated values, skip objects.
189+
- `'long'`: display line-separated key-value pairs, represent object values as their type name.
190+
- `'long-with-objects'`: same as `'long'`, but with full object definitions.
191+
192+
Default labelling behaviour can be overridden with the `label` slot.
193+
194+
```html
195+
<!-- Using `label` slot prop -->
196+
<Cartesian
197+
props={props}
198+
Component={Component}
199+
labels
200+
>
201+
<div class="label-container" slot="label" let:label>
202+
<span class="label">Props</span>
203+
<pre class="props">{label}</pre>
204+
</div>
205+
</Cartesian>
206+
207+
<!--
208+
Using `innerProps` slot prop.
209+
210+
Note: `label` prop isn't required when
211+
using `innerProps` to render labels.
212+
-->
213+
<Cartesian
214+
props={props}
215+
Component={Component}
216+
>
217+
<div class="label-container" slot="label" let:innerProps>
218+
<span class="label">Props</span>
219+
<pre class="props">{customLabel(innerProps)}</pre>
220+
</div>
221+
</Cartesian>
222+
```
223+
171224
### Styling `<Cartesian>` (Svelte 4)
172225
173226
`<Cartesian>` has these default CSS behaviours:
@@ -210,14 +263,23 @@ There are a few ways to override its styles:
210263
211264
### `<Cartesian>` props (Svelte 4)
212265
213-
| prop | type | description |
214-
| ---------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
215-
| `Component` | `ComponentType` | **Required**: A Svelte component. |
216-
| `props` | `Record<string, any[]>` | **Required**: An object containing prop names and an array of potential values. |
217-
| `asChild` | `?boolean=false` | Renders the default slot's contents. Each Cartesian's iteration will pass `innerProps` as slot props. Default value `false`. |
218-
| `unstyled` | `?boolean=false` | Disable built-in CSS. |
219-
| `divAttributes` | `?SvelteHTMLElements["div"]={}` | Attributes to be spread onto the wrapping `<div>` element. |
220-
| `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. |
266+
| prop | type | description |
267+
| ---------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
268+
| `Component` | `ComponentType` | **Required**: A Svelte component. |
269+
| `props` | `Record<string, any[]>` | **Required**: An object containing prop names and an array of potential values. |
270+
| `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. |
271+
| `labels` | `?(undefined \| boolean \| 'short' \| 'long' \| 'long-with-objects')=undefined` | Generate labels under every iteration. See [adding labels](#adding-labels-svelte-4) for detailed usage. |
272+
| `unstyled` | `?boolean=false` | Disable built-in CSS. |
273+
| `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. |
275+
| `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. |
276+
277+
### `<Cartesian>` slots (Svelte 4)
278+
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. |
221283
222284
### Examples (Svelte 4)
223285

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@
4444

4545
<h2>Custom label, object value</h2>
4646

47-
<Cartesian {...props} labels="long-with-objects">
47+
<Cartesian {...props}>
4848
Make popcorn
4949
<div class="label-container" slot="label" let:innerProps>
5050
<span class="label">Props</span>

‎lib/Cartesian.svelte

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,11 @@
2121
/**
2222
* Generate labels under every iteration.
2323
*
24-
* - **true**: same as `'short'`.
25-
* - **short**: display comma-separated values, skip objects.
26-
* - **long**: display line-separated key-value pairs, represent object values
24+
* - `'true'`: same as `'short'`.
25+
* - '`short'`: display comma-separated values, skip objects.
26+
* - '`long'`: display line-separated key-value pairs, represent object values
2727
* as their type name.
28-
* - **long-with-objects**: same as `'long'` but with full object definitions.
28+
* - '`long-with-objects'`: same as `'long'` but with full object definitions.
2929
* @type {undefined | boolean | 'short' | 'long' | 'long-with-objects'}
3030
* @default undefined
3131
*/
@@ -44,6 +44,7 @@
4444
export let divAttributes = {}
4545
4646
const cartesianProps = getCartesianProduct(props)
47+
const showLabels = labels || $$slots.label
4748
</script>
4849

4950
<!--
@@ -54,13 +55,14 @@
5455

5556
<div class:sc-container={!unstyled} {...divAttributes}>
5657
{#each cartesianProps as innerProps}
57-
{@const label = labels && createLabel(innerProps, { verbosity: labels })}
58+
{@const label =
59+
showLabels && createLabel(innerProps, { verbosity: labels })}
5860
<div class="sc-group">
5961
{#if asChild}
6062
<div>
6163
<slot {innerProps} />
6264
</div>
63-
{#if labels}
65+
{#if showLabels}
6466
<div>
6567
<slot name="label" {label} {innerProps}>
6668
<pre class="sc-label">{label}</pre>
@@ -73,7 +75,7 @@
7375
<slot />
7476
</svelte:component>
7577
</div>
76-
{#if labels}
78+
{#if showLabels}
7779
<div>
7880
<slot name="label" {label} {innerProps}>
7981
<pre class="sc-label">{label}</pre>

‎lib/Cartesian.svelte.d.ts

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,11 +17,12 @@ interface Props {
1717
/**
1818
* Generate labels under every iteration.
1919
*
20-
* - **true**: same as `'short'`.
21-
* - **short**: display comma-separated values, skip objects.
22-
* - **long**: display line-separated key-value pairs, represent object values
20+
* - `'true'`: same as `'short'`.
21+
* - '`short'`: display comma-separated values, skip objects.
22+
* - '`long'`: display line-separated key-value pairs, represent object values
2323
* as their type name.
24-
* - **long-with-objects**: same as `'long'` but with full object definitions.
24+
* - '`long-with-objects'`: same as `'long'` but with full object definitions.
25+
* @type {undefined | boolean | 'short' | 'long' | 'long-with-objects'}
2526
* @default undefined
2627
*/
2728
labels?: undefined | boolean | 'short' | 'long' | 'long-with-objects'

0 commit comments

Comments
 (0)