Skip to content

Commit 2b9dcbd

Browse files
committed
[svelte] Correct guide
1 parent b1e608a commit 2b9dcbd

1 file changed

Lines changed: 58 additions & 57 deletions

File tree

site/guides/02_building_uis/6_building_uis_with_svelte.md

Lines changed: 58 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -11,26 +11,26 @@ Install TinyBase and Svelte together:
1111
npm install tinybase svelte
1212
```
1313

14-
Then import hooks and components directly from the `tinybase/ui-svelte` module
15-
in your component's `<script>` block.
14+
Then import functions and components directly from the `tinybase/ui-svelte`
15+
module in your component's `<script>` block.
1616

17-
## Reactive Hooks
17+
## Reactive Functions
1818

19-
Every hook in the `ui-svelte` module returns a reactive object with a `current`
20-
property. Because `current` is backed by Svelte's `$state` rune, any part of
21-
your template that reads it will automatically update when the underlying Store
22-
data changes.
19+
Every reactive function in the `ui-svelte` module returns a reactive object
20+
with a `current` property. Any part of your template that reads it will
21+
automatically update when the underlying Store data changes.
2322

24-
Here is the `useCell` hook reading the color of a pet and displaying it in a
23+
Here is the `createCell` function reading the color of a pet and displaying it
24+
in a
2525
paragraph:
2626

2727
```svelte
2828
<script>
2929
import {createStore} from 'tinybase';
30-
import {useCell} from 'tinybase/ui-svelte';
30+
import {createCell} from 'tinybase/ui-svelte';
3131
3232
const store = createStore().setCell('pets', 'fido', 'color', 'brown');
33-
const color = useCell('pets', 'fido', 'color', store);
33+
const color = createCell('pets', 'fido', 'color', store);
3434
</script>
3535
3636
<p>Color: {color.current}</p>
@@ -39,65 +39,66 @@ paragraph:
3939

4040
When `store.setCell('pets', 'fido', 'color', 'walnut')` is called anywhere, the
4141
paragraph immediately re-renders to show `walnut`. No manual subscriptions, no
42-
`$:` labels, no `onDestroy` cleanup — the hook registers and removes TinyBase
43-
listeners automatically using Svelte's `$effect` lifecycle.
44-
45-
There are hooks corresponding to every Store reading method:
46-
47-
- `useValues` — reactive equivalent of `getValues`
48-
- `useValueIds` — reactive equivalent of `getValueIds`
49-
- `useValue` — reactive equivalent of `getValue`
50-
- `useHasValues` — reactive equivalent of `hasValues`
51-
- `useTables` — reactive equivalent of `getTables`
52-
- `useTableIds` — reactive equivalent of `getTableIds`
53-
- `useTable` — reactive equivalent of `getTable`
54-
- `useRowIds` — reactive equivalent of `getRowIds`
55-
- `useSortedRowIds` — reactive equivalent of `getSortedRowIds`
56-
- `useRow` — reactive equivalent of `getRow`
57-
- `useCellIds` — reactive equivalent of `getCellIds`
58-
- `useCell` — reactive equivalent of `getCell`
59-
60-
There are also hooks for the higher-level TinyBase objects: `useMetric`,
61-
`useMetricIds`, `useSliceIds`, `useSliceRowIds`, `useResultCell`,
62-
`useResultRow`, `useResultTable`, `useResultRowIds`, `useCheckpointIds`,
63-
`useCheckpoint`, and more.
42+
`$:` labels, no `onDestroy` cleanup. The reactive object registers and removes
43+
TinyBase listeners automatically using Svelte's reactivity lifecycle.
44+
45+
There are reactive functions corresponding to every Store reading method:
46+
47+
- `createValues` — reactive equivalent of `getValues`
48+
- `createValueIds` — reactive equivalent of `getValueIds`
49+
- `createValue` — reactive equivalent of `getValue`
50+
- `createHasValues` — reactive equivalent of `hasValues`
51+
- `createTables` — reactive equivalent of `getTables`
52+
- `createTableIds` — reactive equivalent of `getTableIds`
53+
- `createTable` — reactive equivalent of `getTable`
54+
- `createRowIds` — reactive equivalent of `getRowIds`
55+
- `createSortedRowIds` — reactive equivalent of `getSortedRowIds`
56+
- `createRow` — reactive equivalent of `getRow`
57+
- `createCellIds` — reactive equivalent of `getCellIds`
58+
- `createCell` — reactive equivalent of `getCell`
59+
60+
There are also reactive functions for the higher-level TinyBase objects:
61+
`createMetric`, `createMetricIds`, `createSliceIds`, `createSliceRowIds`,
62+
`createResultCell`, `createResultRow`, `createResultTable`,
63+
`createResultRowIds`, `createCheckpointIds`, `createCheckpoint`, and more.
6464

6565
## Reactive Parameters With R
6666

67-
All hook parameters accept either a plain value or a reactive getter function.
68-
This is the `MaybeGetter<T>` type: `T | (() => T)`.
67+
All function parameters accept either a plain value or a reactive getter
68+
function. This is the `MaybeGetter<T>` type: `T | (() => T)`.
6969

70-
Passing a getter function that reads a `$state` variable makes the hook
70+
Passing a getter function that reads a `$state` variable makes the function
7171
reactively track which data it fetches. In this example, `rowId` is a prop and
72-
the hook re-fetches automatically when it changes:
72+
the function re-fetches automatically when it changes:
7373

7474
```svelte
7575
<script>
76-
import {useCell} from 'tinybase/ui-svelte';
76+
import {createCell} from 'tinybase/ui-svelte';
7777
7878
let {rowId, store} = $props();
79-
const color = useCell('pets', () => rowId, 'color', store);
79+
const color = createCell('pets', () => rowId, 'color', store);
8080
</script>
8181
8282
<p>{color.current}</p>
8383
```
8484

8585
Without the `() => rowId` wrapper, changing the `rowId` prop would not cause
86-
the hook to re-read the Store for the new row.
86+
the function to re-read the Store for the new row.
8787

88-
## Writable State With useBindableCell
88+
## Writable State With createCell
8989

90-
The `useBindableCell` and `useBindableValue` hooks expose a writable `current`
91-
property. Writing to it calls `store.setCell()` or `store.setValue()`. This
92-
makes Svelte's `bind:value` directive work for two-way binding:
90+
The `createCell` and `createValue` functions expose a writable `current`
91+
property for scalar values. Writing to it calls `store.setCell()` or
92+
`store.setValue()`. This makes Svelte's `bind:value` directive work for
93+
two-way binding:
9394

9495
```svelte
9596
<script>
9697
import {createStore} from 'tinybase';
97-
import {useBindableCell} from 'tinybase/ui-svelte';
98+
import {createCell} from 'tinybase/ui-svelte';
9899
99100
const store = createStore().setCell('pets', 'fido', 'color', 'brown');
100-
const color = useBindableCell('pets', 'fido', 'color', store);
101+
const color = createCell('pets', 'fido', 'color', store);
101102
</script>
102103
103104
<input bind:value={color.current} />
@@ -109,9 +110,9 @@ in the paragraph — without any additional event handling.
109110

110111
## Context With Provider
111112

112-
For larger apps, passing the `store` object to every hook as the last argument
113-
gets repetitive. The `Provider` component sets a context that all descendant
114-
hooks use automatically when no explicit reference is given:
113+
For larger apps, passing the `store` object to every function as the last
114+
argument gets repetitive. The `Provider` component sets a context that all
115+
descendant functions use automatically when no explicit reference is given:
115116

116117
```svelte
117118
<!-- App.svelte -->
@@ -133,25 +134,25 @@ hooks use automatically when no explicit reference is given:
133134
```svelte
134135
<!-- Pane.svelte -->
135136
<script>
136-
import {useCell} from 'tinybase/ui-svelte';
137+
import {createCell} from 'tinybase/ui-svelte';
137138
138-
// No store argument resolved automatically from the nearest Provider
139-
const species = useCell('pets', 'fido', 'species');
140-
const color = useCell('pets', 'fido', 'color');
139+
// No store argument; resolved automatically from the nearest Provider
140+
const species = createCell('pets', 'fido', 'species');
141+
const color = createCell('pets', 'fido', 'color');
141142
</script>
142143
143144
<p>{species.current} ({color.current})</p>
144145
```
145146

146147
`Provider` accepts `store`, `storesById`, `metrics`, `metricsById`, and
147148
equivalent props for every TinyBase object type. When multiple stores are
148-
provided, hooks reference them by Id:
149+
provided, functions reference them by Id:
149150

150151
```svelte
151152
<script>
152-
import {useCell} from 'tinybase/ui-svelte';
153+
import {createCell} from 'tinybase/ui-svelte';
153154
154-
const color = useCell('pets', 'fido', 'color', 'petStore');
155+
const color = createCell('pets', 'fido', 'color', 'petStore');
155156
</script>
156157
```
157158

@@ -162,8 +163,8 @@ functions.
162163
## View Components
163164

164165
For common rendering tasks, the module provides pre-built view components that
165-
wrap the hooks and render data directly. These make it easy to compose UIs from
166-
Store data:
166+
wrap the reactive functions and render data directly. These make it easy to
167+
compose UIs from Store data:
167168

168169
```svelte
169170
<script>

0 commit comments

Comments
 (0)