[docs] v3.3 Guides

Author: jamesgpearce

site/guides/10_releases.md

@@ -3,6 +3,70 @@
 This is a reverse chronological list of the major TinyBase releases, with
 highlighted features.
 
+## v3.3
+
+This release allows you to track the Cell Ids used across a whole Table,
+regardless of which Row they are in.
+
+In a Table (particularly in a Store without a TablesSchema), different Rows can
+use different Cells. Consider this Store, where each pet has a different set of
+Cell Ids:
+
+```js
+const store = createStore();
+
+store.setTable('pets', {
+  fido: {species: 'dog'},
+  felix: {species: 'cat', friendly: true},
+  cujo: {legs: 4},
+});
+```
+
+Prior to v3.3, you could only get the Cell Ids used in each Row at a time (with
+the getCellIds method). But you can now use the getTableCellIds method to get
+the union of all the Cell Ids used across the Table:
+
+```js
+console.log(store.getCellIds('pets', 'fido')); // previously available
+// -> ['species']
+
+console.log(store.getTableCellIds('pets')); //    new in v3.3
+// -> ['species', 'friendly', 'legs']
+```
+
+You can register a listener to track the Cell Ids used across a Table with the
+new addTableCellIdsListener method. Use cases for this might include knowing
+which headers to render when displaying a sparse Table in a user interface, or
+synchronizing data with relational or column-oriented database system.
+
+There is also a corresponding useTableCellIds hook in the optional ui-react
+module for accessing these Ids reactively, and a useTableCellIdsListener hook
+for more advanced purposes.
+
+Note that the bookkeeping behind these new accessors and listeners is efficient
+and should not be slowed by the number of Rows in the Table.
+
+This release also passes a getIdChanges function to every Id-related listener
+that, when called, returns information about the Id changes, both additions and
+removals, during a transaction. See the TableIdsListener type, for example.
+
+```js
+let listenerId = store.addRowIdsListener(
+  'pets',
+  (store, tableId, getIdChanges) => {
+    console.log(getIdChanges());
+  },
+);
+
+store.setRow('pets', 'lowly', {species: 'worm'});
+// -> {lowly: 1}
+
+store.delRow('pets', 'felix');
+// -> {felix: -1}
+
+store.delListener(listenerId).delTables();
+```
+
 ## v3.2
 
 This release lets you add a listener to the start of a transaction, and detect
@@ -17,8 +81,6 @@ Transactions added with the existing addDidFinishTransactionListener method
 _cannot_ mutate data.
 
 ```js
-const store = createStore();
-
 const startListenerId = store.addStartTransactionListener(() => {
   console.log('Start transaction');
   console.log(store.getTables());
@@ -112,7 +174,7 @@ store.setValues({employees: 3, open: true});
 console.log(store.getValues());
 // -> {employees: 3, open: true}
 
-const listenerId = store.addValueListener(
+listenerId = store.addValueListener(
   null,
   (store, valueId, newValue, oldValue) => {
     console.log(`Value '${valueId}' changed from ${oldValue} to ${newValue}`);

site/guides/1_the_basics/4_reading_from_stores.md

@@ -113,7 +113,8 @@ console.log(store.getCellIds('pets', 'fido'));
 ```
 
 There is also the getSortedRowIds method that lets you get the Ids sorted by a
-specific Cell Id.
+specific Cell Id, and the getTableCellIds method that lets you get all the Ids
+used across a whole Table.
 
 Again, the return types of these methods are by value, not by reference. So if
 you manipulate the returned array, the Store is not updated:

site/guides/1_the_basics/5_listening_to_stores.md

@@ -15,6 +15,7 @@ And for tabular data:
 - Listen to Tables with the addTablesListener method.
 - Listen to Table Ids with the addTableIdsListener method.
 - Listen to a Table with the addTableListener method.
+- Listen to Cells Ids across a Table with the addTableCellIdsListener method.
 - Listen to Row Ids with the addRowIdsListener method.
 - Listen to sorted Row Ids with the addSortedRowIdsListener method.
 - Listen to a Row with the addRowListener method.

site/guides/2_building_uis/2_using_react_hooks.md

@@ -39,6 +39,7 @@ And for tabular data:
 - The useTables hook is the reactive equivalent of the getTables method.
 - The useTableIds hook is the reactive equivalent of the getTableIds method.
 - The useTable hook is the reactive equivalent of the getTable method.
+- The useTableCellIds hook is the reactive equivalent of the getTableCellIds method.
 - The useRowIds hook is the reactive equivalent of the getRowIds method.
 - The useSortedRowIds hook is the reactive equivalent of the getSortedRowIds method.
 - The useRow hook is the reactive equivalent of the getRow method.

site/home/index.md

@@ -56,7 +56,7 @@
   </p>
 </section>
 
-<a id='new' href='/guides/releases/#v3-2'><em>NEW!</em> v3.2 release</a>
+<a id='new' href='/guides/releases/#v3-3'><em>NEW!</em> v3.3 release</a>
 
 ---
 

src/types/docs/store.js

@@ -1059,6 +1059,7 @@
  * |Tables|getTables|setTables|delTables|addTablesListener|
  * |Table Ids|getTableIds|-|-|addTableIdsListener|
  * |Table|getTable|setTable|delTable|addTableListener|
+ * |Table Cell Ids|getTableCellIds|-|-|addTableCellIdsListener|
  * |Row Ids|getRowIds|-|-|addRowIdsListener|
  * |Row Ids (sorted)|getSortedRowIds|-|-|addSortedRowIdsListener|
  * |Row|getRow|setRow|delRow|addRowListener|