tinybase 7.2.0-beta.2 → 7.2.0

package/@types/ui-react/with-schemas/index.d.ts

@@ -100,7 +100,9 @@ import type {
 } from '../../persisters/with-schemas/index.d.ts';
 import type {
   ParamValue,
+  ParamValueListener,
   ParamValues,
+  ParamValuesListener,
   Queries,
   ResultCell,
   ResultCellIdsListener,
@@ -11777,8 +11779,520 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
   ) => void;
 
   /**
- * The useSetParamValueCallback hook returns a parameterized callback that
- * can be used to set a single parameter value for a query.
+ * The useParamValues hook returns an object containing all the parameter values
+ * currently set for a query.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useParamValues(
+ *   queryId: Id,
+ *   queriesOrQueriesId?: QueriesOrQueriesId,
+ * ): ParamValues | undefined;
+ * ```
+ *
+ * A Provider component is used to wrap part of an application in a context, and
+ * it can contain a default Queries object or a set of Queries objects named by
+ * Id. The useParamValues hook lets you indicate which Queries object to get
+ * data for: omit the optional final parameter for the default context Queries
+ * object, provide an Id for a named context Queries object, or provide a
+ * Queries object explicitly by reference.
+ *
+ * When first rendered, this hook will create a listener so that changes to the
+ * parameter values will cause a re-render. When the component containing this
+ * hook is unmounted, the listener will be automatically removed.
+ * @param queryId The Id of the query to get parameter values for.
+ * @param queriesOrQueriesId The Queries object to be accessed: omit for the
+ * default context Queries object, provide an Id for a named context Queries
+ * object, or provide an explicit reference.
+ * @returns An object containing all parameter values for the query, or
+ * undefined if the query doesn't exist.
+ * @example
+ * This example creates a Queries object outside the application, which is used
+ * in the useParamValues hook by reference. A change to the parameter values
+ * re-renders the component.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createQueries, createStore} from 'tinybase';
+ * import {createRoot} from 'react-dom/client';
+ * import {useParamValues} from 'tinybase/ui-react';
+ *
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog', color: 'brown'},
+ *   felix: {species: 'cat', color: 'black'},
+ * });
+ * const queries = createQueries(store);
+ * queries.setQueryDefinition(
+ *   'petsBySpecies',
+ *   'pets',
+ *   ({select, where, param}) => {
+ *     select('species');
+ *     where('species', param('species'));
+ *   },
+ *   {species: 'dog'},
+ * );
+ *
+ * const App = () => (
+ *   <span>{JSON.stringify(useParamValues('petsBySpecies', queries))}</span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>{"species":"dog"}</span>'
+ *
+ * queries.setParamValue('petsBySpecies', 'species', 'cat'); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>{"species":"cat"}</span>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a default Queries object
+ * is provided. A component within it then uses the useParamValues hook.
+ *
+ * ```jsx
+ * import {Provider, useParamValues} from 'tinybase/ui-react';
+ * import React from 'react';
+ * import {createQueries, createStore} from 'tinybase';
+ * import {createRoot} from 'react-dom/client';
+ *
+ * const App = ({queries}) => (
+ *   <Provider queries={queries}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <span>{JSON.stringify(useParamValues('petsBySpecies'))}</span>
+ * );
+ *
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ * });
+ * const queries = createQueries(store);
+ * queries.setQueryDefinition(
+ *   'petsBySpecies',
+ *   'pets',
+ *   ({select, where, param}) => {
+ *     select('species');
+ *     where('species', param('species'));
+ *   },
+ *   {species: 'dog'},
+ * );
+ *
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App queries={queries} />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>{"species":"dog"}</span>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a Queries object is
+ * provided, named by Id. A component within it then uses the useParamValues
+ * hook.
+ *
+ * ```jsx
+ * import {Provider, useParamValues} from 'tinybase/ui-react';
+ * import React from 'react';
+ * import {createQueries, createStore} from 'tinybase';
+ * import {createRoot} from 'react-dom/client';
+ *
+ * const App = ({queries}) => (
+ *   <Provider queriesById={{petQueries: queries}}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <span>
+ *     {JSON.stringify(useParamValues('petsBySpecies', 'petQueries'))}
+ *   </span>
+ * );
+ *
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ * });
+ * const queries = createQueries(store);
+ * queries.setQueryDefinition(
+ *   'petsBySpecies',
+ *   'pets',
+ *   ({select, where, param}) => {
+ *     select('species');
+ *     where('species', param('species'));
+ *   },
+ *   {species: 'dog'},
+ * );
+ *
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App queries={queries} />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>{"species":"dog"}</span>'
+ * ```
+ * @category Queries hooks
+ * @since v7.2.0
+ */
+  useParamValues: (
+    queryId: Id,
+    queriesOrQueriesId?: QueriesOrQueriesId<Schemas>,
+  ) => ParamValues | undefined;
+
+  /**
+ * The useParamValue hook returns the current value of a single parameter in a
+ * query.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useParamValue(
+ *   queryId: Id,
+ *   paramId: Id,
+ *   queriesOrQueriesId?: QueriesOrQueriesId,
+ * ): ParamValue | undefined;
+ * ```
+ *
+ * A Provider component is used to wrap part of an application in a context, and
+ * it can contain a default Queries object or a set of Queries objects named by
+ * Id. The useParamValue hook lets you indicate which Queries object to get data
+ * for: omit the optional final parameter for the default context Queries
+ * object, provide an Id for a named context Queries object, or provide a
+ * Queries object explicitly by reference.
+ *
+ * When first rendered, this hook will create a listener so that changes to the
+ * parameter value will cause a re-render. When the component containing this
+ * hook is unmounted, the listener will be automatically removed.
+ * @param queryId The Id of the query to get the parameter value from.
+ * @param paramId The Id of the parameter to get the value of.
+ * @param queriesOrQueriesId The Queries object to be accessed: omit for the
+ * default context Queries object, provide an Id for a named context Queries
+ * object, or provide an explicit reference.
+ * @returns The value of the parameter, or undefined if it doesn't exist.
+ * @example
+ * This example creates a Queries object outside the application, which is used
+ * in the useParamValue hook by reference. A change to the parameter value
+ * re-renders the component.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createQueries, createStore} from 'tinybase';
+ * import {createRoot} from 'react-dom/client';
+ * import {useParamValue} from 'tinybase/ui-react';
+ *
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog', color: 'brown'},
+ *   felix: {species: 'cat', color: 'black'},
+ * });
+ * const queries = createQueries(store);
+ * queries.setQueryDefinition(
+ *   'petsBySpecies',
+ *   'pets',
+ *   ({select, where, param}) => {
+ *     select('species');
+ *     where('species', param('species'));
+ *   },
+ *   {species: 'dog'},
+ * );
+ *
+ * const App = () => (
+ *   <span>{useParamValue('petsBySpecies', 'species', queries)}</span>
+ * );
+ *
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>dog</span>'
+ *
+ * queries.setParamValue('petsBySpecies', 'species', 'cat'); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>cat</span>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a default Queries object
+ * is provided. A component within it then uses the useParamValue hook.
+ *
+ * ```jsx
+ * import {Provider, useParamValue} from 'tinybase/ui-react';
+ * import React from 'react';
+ * import {createQueries, createStore} from 'tinybase';
+ * import {createRoot} from 'react-dom/client';
+ *
+ * const App = ({queries}) => (
+ *   <Provider queries={queries}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <span>{useParamValue('petsBySpecies', 'species')}</span>
+ * );
+ *
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ * });
+ * const queries = createQueries(store);
+ * queries.setQueryDefinition(
+ *   'petsBySpecies',
+ *   'pets',
+ *   ({select, where, param}) => {
+ *     select('species');
+ *     where('species', param('species'));
+ *   },
+ *   {species: 'dog'},
+ * );
+ *
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App queries={queries} />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>dog</span>'
+ * ```
+ * @example
+ * This example creates a Provider context into which a Queries object is
+ * provided, named by Id. A component within it then uses the useParamValue
+ * hook.
+ *
+ * ```jsx
+ * import {Provider, useParamValue} from 'tinybase/ui-react';
+ * import React from 'react';
+ * import {createQueries, createStore} from 'tinybase';
+ * import {createRoot} from 'react-dom/client';
+ *
+ * const App = ({queries}) => (
+ *   <Provider queriesById={{petQueries: queries}}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => (
+ *   <span>{useParamValue('petsBySpecies', 'species', 'petQueries')}</span>
+ * );
+ *
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ * });
+ * const queries = createQueries(store);
+ * queries.setQueryDefinition(
+ *   'petsBySpecies',
+ *   'pets',
+ *   ({select, where, param}) => {
+ *     select('species');
+ *     where('species', param('species'));
+ *   },
+ *   {species: 'dog'},
+ * );
+ *
+ * const app = document.createElement('div');
+ * createRoot(app).render(<App queries={queries} />); // !act
+ * console.log(app.innerHTML);
+ * // -> '<span>dog</span>'
+ * ```
+ * @category Queries hooks
+ * @since v7.2.0
+ */
+  useParamValue: (
+    queryId: Id,
+    paramId: Id,
+    queriesOrQueriesId?: QueriesOrQueriesId<Schemas>,
+  ) => ParamValue | undefined;
+
+  /**
+ * The useParamValuesListener hook registers a listener function with a Queries
+ * object that will be called whenever the parameter values for a query change.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useParamValuesListener(
+ *   queryId: IdOrNull,
+ *   listener: ParamValuesListener,
+ *   listenerDeps?: React.DependencyList,
+ *   queriesOrQueriesId?: QueriesOrQueriesId,
+ * ): void;
+ * ```
+ *
+ * This hook is useful for situations where a component needs to register its
+ * own specific listener to do more than simply tracking the values (which is
+ * more easily done with the useParamValues hook).
+ *
+ * Unlike the addParamValuesListener method, which returns a listener Id and
+ * requires you to remove it manually, the useParamValuesListener hook manages
+ * this lifecycle for you: when the listener changes (per its `listenerDeps`
+ * dependencies) or the component unmounts, the listener on the underlying
+ * Queries object will be deleted.
+ * @param queryId The Id of the query to listen to, or `null` as a wildcard.
+ * @param listener The function that will be called whenever the parameter
+ * values for the query change.
+ * @param listenerDeps An optional array of dependencies for the `listener`
+ * function, which, if any change, result in the re-registration of the
+ * listener. This parameter defaults to an empty array.
+ * @param queriesOrQueriesId The Queries object to register the listener with:
+ * omit for the default context Queries object, provide an Id for a named
+ * context Queries object, or provide an explicit reference.
+ * @example
+ * This example uses the useParamValuesListener hook to create a listener that
+ * is scoped to a single component. When the component is unmounted, the
+ * listener is removed from the Queries object.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createQueries, createStore} from 'tinybase';
+ * import {Provider, useParamValuesListener} from 'tinybase/ui-react';
+ *
+ * const App = ({queries}) => (
+ *   <Provider queries={queries}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => {
+ *   useParamValuesListener('petsBySpecies', () =>
+ *     console.log('Param values changed'),
+ *   );
+ *   return <span>App</span>;
+ * };
+ *
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ * });
+ * const queries = createQueries(store);
+ * queries.setQueryDefinition(
+ *   'petsBySpecies',
+ *   'pets',
+ *   ({select, where, param}) => {
+ *     select('species');
+ *     where('species', param('species'));
+ *   },
+ *   {species: 'dog'},
+ * );
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App queries={queries} />); // !act
+ * console.log(queries.getListenerStats().paramValues);
+ * // -> 1
+ *
+ * queries.setParamValue('petsBySpecies', 'species', 'cat'); // !act
+ * // -> 'Param values changed'
+ *
+ * root.unmount(); // !act
+ * console.log(queries.getListenerStats().paramValues);
+ * // -> 0
+ * ```
+ * @category Queries hooks
+ * @since v7.2.0
+ */
+  useParamValuesListener: (
+    queryId: IdOrNull,
+    listener: ParamValuesListener<Schemas>,
+    listenerDeps?: React.DependencyList,
+    queriesOrQueriesId?: QueriesOrQueriesId<Schemas>,
+  ) => void;
+
+  /**
+ * The useParamValueListener hook registers a listener function with a Queries
+ * object that will be called whenever a single parameter value for a query
+ * changes.
+ *
+ * This has schema-based typing. The following is a simplified representation:
+ *
+ * ```ts override
+ * useParamValueListener(
+ *   queryId: IdOrNull,
+ *   paramId: IdOrNull,
+ *   listener: ParamValueListener,
+ *   listenerDeps?: React.DependencyList,
+ *   queriesOrQueriesId?: QueriesOrQueriesId,
+ * ): void;
+ * ```
+ *
+ * This hook is useful for situations where a component needs to register its
+ * own specific listener to do more than simply tracking the value (which is
+ * more easily done with the useParamValue hook).
+ *
+ * You can either listen to a single parameter (by specifying the query Id and
+ * parameter Id as the method's first two parameters) or changes to any
+ * parameter (by providing `null` wildcards).
+ *
+ * Both the `queryId` and `paramId` parameters can be wildcarded with `null`.
+ * You can listen to a specific parameter in a specific query, any parameter in
+ * any query, for example - or every other combination of wildcards.
+ *
+ * Unlike the addParamValueListener method, which returns a listener Id and
+ * requires you to remove it manually, the useParamValueListener hook manages
+ * this lifecycle for you: when the listener changes (per its `listenerDeps`
+ * dependencies) or the component unmounts, the listener on the underlying
+ * Queries object will be deleted.
+ * @param queryId The Id of the query to listen to, or `null` as a wildcard.
+ * @param paramId The Id of the parameter to listen to, or `null` as a wildcard.
+ * @param listener The function that will be called whenever the parameter value
+ * changes.
+ * @param listenerDeps An optional array of dependencies for the `listener`
+ * function, which, if any change, result in the re-registration of the
+ * listener. This parameter defaults to an empty array.
+ * @param queriesOrQueriesId The Queries object to register the listener with:
+ * omit for the default context Queries object, provide an Id for a named
+ * context Queries object, or provide an explicit reference.
+ * @example
+ * This example uses the useParamValueListener hook to create a listener that
+ * is scoped to a single component. When the component is unmounted, the
+ * listener is removed from the Queries object.
+ *
+ * ```jsx
+ * import React from 'react';
+ * import {createRoot} from 'react-dom/client';
+ * import {createQueries, createStore} from 'tinybase';
+ * import {Provider, useParamValueListener} from 'tinybase/ui-react';
+ *
+ * const App = ({queries}) => (
+ *   <Provider queries={queries}>
+ *     <Pane />
+ *   </Provider>
+ * );
+ * const Pane = () => {
+ *   useParamValueListener('petsBySpecies', 'species', () =>
+ *     console.log('Param value changed'),
+ *   );
+ *   return <span>App</span>;
+ * };
+ *
+ * const store = createStore().setTable('pets', {
+ *   fido: {species: 'dog'},
+ *   felix: {species: 'cat'},
+ * });
+ * const queries = createQueries(store);
+ * queries.setQueryDefinition(
+ *   'petsBySpecies',
+ *   'pets',
+ *   ({select, where, param}) => {
+ *     select('species');
+ *     where('species', param('species'));
+ *   },
+ *   {species: 'dog'},
+ * );
+ * const app = document.createElement('div');
+ * const root = createRoot(app);
+ * root.render(<App queries={queries} />); // !act
+ * console.log(queries.getListenerStats().paramValue);
+ * // -> 1
+ *
+ * queries.setParamValue('petsBySpecies', 'species', 'cat'); // !act
+ * // -> 'Param value changed'
+ *
+ * root.unmount(); // !act
+ * console.log(queries.getListenerStats().paramValue);
+ * // -> 0
+ * ```
+ * @category Queries hooks
+ * @since v7.2.0
+ */
+  useParamValueListener: (
+    queryId: IdOrNull,
+    paramId: IdOrNull,
+    listener: ParamValueListener<Schemas>,
+    listenerDeps?: React.DependencyList,
+    queriesOrQueriesId?: QueriesOrQueriesId<Schemas>,
+  ) => void;
+
+  /**
+ * The useSetParamValueCallback hook returns a parameterized callback that can
+ * be used to set a single parameter value for a query.
  *
  * This has schema-based typing. The following is a simplified representation:
  *
@@ -11843,10 +12357,7 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
  * import React from 'react';
  * import {createRoot} from 'react-dom/client';
  * import {createQueries, createStore} from 'tinybase';
- * import {
- *   useResultTable,
- *   useSetParamValueCallback,
- * } from 'tinybase/ui-react';
+ * import {useResultTable, useSetParamValueCallback} from 'tinybase/ui-react';
  *
  * const store = createStore().setTable('pets', {
  *   fido: {species: 'dog', color: 'brown'},
@@ -11924,8 +12435,8 @@ export type WithSchemas<Schemas extends OptionalSchemas> = {
   ) => ParameterizedCallback<Parameter>;
 
   /**
- * The useSetParamValuesCallback hook returns a parameterized callback that
- * can be used to set multiple parameter values for a query at once.
+ * The useSetParamValuesCallback hook returns a parameterized callback that can
+ * be used to set multiple parameter values for a query at once.
  *
  * This has schema-based typing. The following is a simplified representation:
  *

package/agents.md

@@ -485,3 +485,37 @@ When adding a new feature:
      `<span id="one-with">"The one with Schematizers!"</span>`
 
 3. **Generated files update automatically** during build process
+
+## Demo Development Workflow
+
+Demos are located in `/site/demos/` as markdown files containing embedded code
+blocks that are assembled into working applications.
+
+### Demo Structure
+
+- **Demo files**: `/site/demos/*.md` or `/site/demos/*/`
+- **E2E tests**: `/test/e2e/demos/*.test.ts`
+- Code blocks in markdown are extracted and combined into complete applications
+- All code fragments in a demo share scope (variables declared in one block are
+  available in subsequent blocks)
+
+### Iteration Workflow
+
+When modifying demos:
+
+```bash
+# One-time setup (only if TinyBase source code has changed)
+npm run compileForProd
+
+# Fast iteration loop
+npm run compileDocsPagesOnly  # Rebuild just the demo pages
+npm run testE2e               # Run E2E tests to verify demos
+```
+
+**Key points**:
+
+- `compileForProd` builds the TinyBase libraries themselves
+- `compileDocsPagesOnly` is much faster - only rebuilds demo pages from markdown
+- You only need `compileForProd` once, unless you've changed TinyBase source
+- E2E tests use Playwright to verify demos work in a real browser
+- Individual E2E tests can be run for faster verification during iteration