[svelte] useBindableX

Author: jamesgpearce

site/guides/02_building_uis/6_building_uis_with_svelte.md

@@ -85,19 +85,19 @@ the hook re-fetches automatically when it changes:
 Without the `() => rowId` wrapper, changing the `rowId` prop would not cause
 the hook to re-read the Store for the new row.
 
-## Writable State With useCellState
+## Writable State With useBindableCell
 
-The `useCellState` and `useValueState` hooks expose a writable `current`
+The `useBindableCell` and `useBindableValue` hooks expose a writable `current`
 property. Writing to it calls `store.setCell()` or `store.setValue()`. This
 makes Svelte's `bind:value` directive work for two-way binding:
 
 ```svelte
 <script>
   import {createStore} from 'tinybase';
-  import {useCellState} from 'tinybase/ui-svelte';
+  import {useBindableCell} from 'tinybase/ui-svelte';
 
   const store = createStore().setCell('pets', 'fido', 'color', 'brown');
-  const color = useCellState('pets', 'fido', 'color', store);
+  const color = useBindableCell('pets', 'fido', 'color', store);
 </script>
 
 <input bind:value={color.current} />

site/guides/17_releases.md

@@ -30,15 +30,15 @@ underlying TinyBase data changes:
 <p>Color: {color.current}</p>
 ```
 
-The `useCellState` and `useValueState` hooks go further, providing a writable
-`current` property that pairs naturally with Svelte's `bind:` directive for
-two-way data binding:
+The `useBindableCell` and `useBindableValue` hooks go further, providing a
+writable `current` property that pairs naturally with Svelte's `bind:`
+directive for two-way data binding:
 
 ```svelte
 <script>
-  import {useCellState} from 'tinybase/ui-svelte';
+  import {useBindableCell} from 'tinybase/ui-svelte';
 
-  const color = useCellState('pets', 'fido', 'color', store);
+  const color = useBindableCell('pets', 'fido', 'color', store);
 </script>
 
 <input bind:value={color.current} />

src/@types/ui-svelte/docs.js

@@ -1308,7 +1308,7 @@
  */
 /// ui-svelte.useCell
 /**
- * The useCellState hook returns a reactive object reflecting the value of a
+ * The useBindableCell hook returns a reactive object reflecting the value of a
  * Cell, with a settable `current` property that writes back to the Store.
  * @param tableId The Id of the Table (or a getter returning it).
  * @param rowId The Id of the Row (or a getter returning it).
@@ -1318,7 +1318,7 @@
  * @category Hook
  * @since v8.1.0
  */
-/// ui-svelte.useCellState
+/// ui-svelte.useBindableCell
 /**
  * The useHasValues hook returns a reactive object indicating whether any Values
  * exist in the Store, and registers a listener so that any changes to that
@@ -1371,15 +1371,15 @@
  */
 /// ui-svelte.useValue
 /**
- * The useValueState hook returns a reactive object reflecting the value of a
+ * The useBindableValue hook returns a reactive object reflecting the value of a
  * Value, with a settable `current` property that writes back to the Store.
  * @param valueId The Id of the Value (or a getter returning it).
  * @param storeOrStoreId The Store to use (plain value or getter), or its Id.
  * @returns A reactive object with gettable and settable `current`.
  * @category Hook
  * @since v8.1.0
  */
-/// ui-svelte.useValueState
+/// ui-svelte.useBindableValue
 /**
  * The useStore hook returns the default Store from the current Provider context
  * (or a named Store if an Id is provided).

src/@types/ui-svelte/index.d.ts

@@ -528,8 +528,8 @@ export function useCell(
   storeOrStoreId?: R<Store | Id | undefined>,
 ): {readonly current: CellOrUndefined};
 
-/// ui-svelte.useCellState
-export function useCellState(
+/// ui-svelte.useBindableCell
+export function useBindableCell(
   tableId: R<Id>,
   rowId: R<Id>,
   cellId: R<Id>,
@@ -563,8 +563,8 @@ export function useValue(
   storeOrStoreId?: R<Store | Id | undefined>,
 ): {readonly current: ValueOrUndefined};
 
-/// ui-svelte.useValueState
-export function useValueState(
+/// ui-svelte.useBindableValue
+export function useBindableValue(
   valueId: R<Id>,
   storeOrStoreId?: R<Store | Id | undefined>,
 ): {get current(): ValueOrUndefined; set current(v: Value)};

src/@types/ui-svelte/with-schemas/index.d.ts

@@ -405,8 +405,8 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     readonly current: NoInfer<CellOrUndefined<Schemas[0], TableId, CellId>>;
   };
 
-  /// ui-svelte.useCellState
-  useCellState: <
+  /// ui-svelte.useBindableCell
+  useBindableCell: <
     TableId extends TableIdFromSchema<Schemas[0]>,
     CellId extends CellIdFromSchema<Schemas[0], TableId>,
   >(
@@ -458,8 +458,8 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
     readonly current: NoInfer<DefaultedValueFromSchema<Schemas[1], ValueId>>;
   };
 
-  /// ui-svelte.useValueState
-  useValueState: <ValueId extends ValueIdFromSchema<Schemas[1]>>(
+  /// ui-svelte.useBindableValue
+  useBindableValue: <ValueId extends ValueIdFromSchema<Schemas[1]>>(
     valueId: ValueId | (() => ValueId),
     storeOrStoreId?: Store<Schemas> | Id,
   ) => {

src/ui-svelte/hooks.svelte.ts

@@ -155,15 +155,17 @@ const useListenable = <T>(
   let value = $state<T>(
     (getThing()?.[getMethod]?.(...getArgs()) ?? defaultValue) as T,
   );
-  $effect(() => {
-    const thing = getThing();
-    const args = getArgs();
-    value = (thing?.[getMethod]?.(...args) ?? defaultValue) as T;
-    const listenerId = thing?.[addMethod]?.(...args, () => {
-      value = (thing[getMethod](...getArgs()) ?? defaultValue) as T;
+  if (typeof window !== 'undefined') {
+    $effect(() => {
+      const thing = getThing();
+      const args = getArgs();
+      value = (thing?.[getMethod]?.(...args) ?? defaultValue) as T;
+      const listenerId = thing?.[addMethod]?.(...args, () => {
+        value = (thing[getMethod](...getArgs()) ?? defaultValue) as T;
+      });
+      return () => thing?.delListener?.(listenerId);
     });
-    return () => thing?.delListener?.(listenerId);
-  });
+  }
   return {
     get current(): T {
       return value as T;
@@ -311,7 +313,7 @@ export const useCell = (
     rv(cellId),
   ]);
 
-export const useCellState = (
+export const useBindableCell = (
   tableId: R<Id>,
   rowId: R<Id>,
   cellId: R<Id>,
@@ -321,17 +323,19 @@ export const useCellState = (
   let value = $state<CellOrUndefined>(
     getS()?.getCell(rv(tableId), rv(rowId), rv(cellId)),
   );
-  $effect(() => {
-    const s: any = getS();
-    const t = rv(tableId),
-      r = rv(rowId),
-      c = rv(cellId);
-    value = s?.getCell(t, r, c);
-    const listenerId = s?.addCellListener(t, r, c, (st: any) => {
-      value = st.getCell(rv(tableId), rv(rowId), rv(cellId));
+  if (typeof window !== 'undefined') {
+    $effect(() => {
+      const s: any = getS();
+      const t = rv(tableId),
+        r = rv(rowId),
+        c = rv(cellId);
+      value = s?.getCell(t, r, c);
+      const listenerId = s?.addCellListener(t, r, c, (st: any) => {
+        value = st.getCell(rv(tableId), rv(rowId), rv(cellId));
+      });
+      return () => s?.delListener?.(listenerId);
     });
-    return () => s?.delListener?.(listenerId);
-  });
+  }
   return {
     get current(): CellOrUndefined {
       return value;
@@ -367,21 +371,23 @@ export const useValue = (
 ): {readonly current: ValueOrUndefined} =>
   useGet(sg(storeOrStoreId), VALUE, undefined, () => [rv(valueId)]);
 
-export const useValueState = (
+export const useBindableValue = (
   valueId: R<Id>,
   storeOrStoreId?: R<Store | Id | undefined>,
 ): {get current(): ValueOrUndefined; set current(v: Value)} => {
   const getS = sg(storeOrStoreId);
   let value = $state<ValueOrUndefined>(getS()?.getValue(rv(valueId)));
-  $effect(() => {
-    const s: any = getS();
-    const vid = rv(valueId);
-    value = s?.getValue(vid);
-    const listenerId = s?.addValueListener(vid, (st: any) => {
-      value = st.getValue(rv(valueId));
+  if (typeof window !== 'undefined') {
+    $effect(() => {
+      const s: any = getS();
+      const vid = rv(valueId);
+      value = s?.getValue(vid);
+      const listenerId = s?.addValueListener(vid, (st: any) => {
+        value = st.getValue(rv(valueId));
+      });
+      return () => s?.delListener?.(listenerId);
     });
-    return () => s?.delListener?.(listenerId);
-  });
+  }
   return {
     get current(): ValueOrUndefined {
       return value;
@@ -398,9 +404,11 @@ export const useStore = (id?: Id): Store | undefined =>
 export const useStoreIds = (): {readonly current: Ids} => {
   const ctx = getCtx();
   let ids = $state<Ids>(getThingIds(ctx, OFFSET_STORE));
-  $effect(() => {
-    ids = getThingIds(ctx, OFFSET_STORE);
-  });
+  if (typeof window !== 'undefined') {
+    $effect(() => {
+      ids = getThingIds(ctx, OFFSET_STORE);
+    });
+  }
   return {
     get current() {
       return ids;
@@ -414,9 +422,11 @@ export const useMetrics = (id?: Id): Metrics | undefined =>
 export const useMetricsIds = (): {readonly current: Ids} => {
   const ctx = getCtx();
   let ids = $state<Ids>(getThingIds(ctx, OFFSET_METRICS));
-  $effect(() => {
-    ids = getThingIds(ctx, OFFSET_METRICS);
-  });
+  if (typeof window !== 'undefined') {
+    $effect(() => {
+      ids = getThingIds(ctx, OFFSET_METRICS);
+    });
+  }
   return {
     get current() {
       return ids;
@@ -441,9 +451,11 @@ export const useIndexes = (id?: Id): Indexes | undefined =>
 export const useIndexesIds = (): {readonly current: Ids} => {
   const ctx = getCtx();
   let ids = $state<Ids>(getThingIds(ctx, OFFSET_INDEXES));
-  $effect(() => {
-    ids = getThingIds(ctx, OFFSET_INDEXES);
-  });
+  if (typeof window !== 'undefined') {
+    $effect(() => {
+      ids = getThingIds(ctx, OFFSET_INDEXES);
+    });
+  }
   return {
     get current() {
       return ids;
@@ -478,9 +490,11 @@ export const useQueries = (id?: Id): Queries | undefined =>
 export const useQueriesIds = (): {readonly current: Ids} => {
   const ctx = getCtx();
   let ids = $state<Ids>(getThingIds(ctx, OFFSET_QUERIES));
-  $effect(() => {
-    ids = getThingIds(ctx, OFFSET_QUERIES);
-  });
+  if (typeof window !== 'undefined') {
+    $effect(() => {
+      ids = getThingIds(ctx, OFFSET_QUERIES);
+    });
+  }
   return {
     get current() {
       return ids;
@@ -577,9 +591,11 @@ export const useRelationships = (id?: Id): Relationships | undefined =>
 export const useRelationshipsIds = (): {readonly current: Ids} => {
   const ctx = getCtx();
   let ids = $state<Ids>(getThingIds(ctx, OFFSET_RELATIONSHIPS));
-  $effect(() => {
-    ids = getThingIds(ctx, OFFSET_RELATIONSHIPS);
-  });
+  if (typeof window !== 'undefined') {
+    $effect(() => {
+      ids = getThingIds(ctx, OFFSET_RELATIONSHIPS);
+    });
+  }
   return {
     get current() {
       return ids;
@@ -630,9 +646,11 @@ export const useCheckpoints = (id?: Id): Checkpoints | undefined =>
 export const useCheckpointsIds = (): {readonly current: Ids} => {
   const ctx = getCtx();
   let ids = $state<Ids>(getThingIds(ctx, OFFSET_CHECKPOINTS));
-  $effect(() => {
-    ids = getThingIds(ctx, OFFSET_CHECKPOINTS);
-  });
+  if (typeof window !== 'undefined') {
+    $effect(() => {
+      ids = getThingIds(ctx, OFFSET_CHECKPOINTS);
+    });
+  }
   return {
     get current() {
       return ids;
@@ -677,9 +695,11 @@ export const usePersister = (id?: Id): AnyPersister | undefined =>
 export const usePersisterIds = (): {readonly current: Ids} => {
   const ctx = getCtx();
   let ids = $state<Ids>(getThingIds(ctx, OFFSET_PERSISTER));
-  $effect(() => {
-    ids = getThingIds(ctx, OFFSET_PERSISTER);
-  });
+  if (typeof window !== 'undefined') {
+    $effect(() => {
+      ids = getThingIds(ctx, OFFSET_PERSISTER);
+    });
+  }
   return {
     get current() {
       return ids;
@@ -698,9 +718,11 @@ export const useSynchronizer = (id?: Id): Synchronizer | undefined =>
 export const useSynchronizerIds = (): {readonly current: Ids} => {
   const ctx = getCtx();
   let ids = $state<Ids>(getThingIds(ctx, OFFSET_SYNCHRONIZER));
-  $effect(() => {
-    ids = getThingIds(ctx, OFFSET_SYNCHRONIZER);
-  });
+  if (typeof window !== 'undefined') {
+    $effect(() => {
+      ids = getThingIds(ctx, OFFSET_SYNCHRONIZER);
+    });
+  }
   return {
     get current() {
       return ids;
@@ -715,10 +737,12 @@ export const useSynchronizerStatus = (
 
 const injectThing = (offset: number, id: Id, thing: any): void => {
   const ctx = getCtx();
-  $effect(() => {
-    ctx[16]?.(offset, id, thing);
-    return () => ctx[17]?.(offset, id);
-  });
+  if (typeof window !== 'undefined') {
+    $effect(() => {
+      ctx[16]?.(offset, id, thing);
+      return () => ctx[17]?.(offset, id);
+    });
+  }
 };
 
 export const provideStore = (storeId: Id, store: Store): void =>

src/ui-svelte/index.ts

@@ -14,7 +14,7 @@ export {
   provideSynchronizer,
   useCell,
   useCellIds,
-  useCellState,
+  useBindableCell,
   useCheckpoint,
   useCheckpointIds,
   useCheckpoints,
@@ -72,7 +72,7 @@ export {
   useTables,
   useValue,
   useValueIds,
-  useValueState,
+  useBindableValue,
   useValues,
 } from './hooks.svelte.ts';
 export {default as IndexView} from './IndexView.svelte';

…e/ui-svelte/helpers/HookCellState.svelte …i-svelte/helpers/HookBindableCell.sveltetest/unit/core/ui-svelte/helpers/HookCellState.svelte renamed to test/unit/core/ui-svelte/helpers/HookBindableCell.svelte test/unit/core/ui-svelte/helpers/HookCellState.svelte renamed to test/unit/core/ui-svelte/helpers/HookBindableCell.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-  import {useCellState} from 'tinybase/ui-svelte';
+  import {useBindableCell} from 'tinybase/ui-svelte';
   import type {Id} from 'tinybase';
   import type {Store} from 'tinybase';
   import type {Cell} from 'tinybase';
@@ -17,7 +17,7 @@
     cellId: Id;
     newValue?: Cell;
   } = $props();
-  const v = useCellState(
+  const v = useBindableCell(
     () => tableId,
     () => rowId,
     () => cellId,