Rename 'childProp' to 'childSource' and fix a few more render bugs

Also finishes out the list view documentation.

Author: blacksmithgu

docs/docs/code-views/list-view.md

@@ -170,7 +170,78 @@ return function View() {
 
 If you group multiple times, you can specify a separate rendering for each grouping level by passing an array of grouping configurations to `groupings`.
 
-### Heirarchies / Children (`childProp` / `maxChildDepth`)
+### Sublists (`childSource` / `maxChildDepth`)
+
+Lists can recursively contain sublists to create full heirarchies of entries. By default, datacore
+will look for the `$children` and `children` properties on rows to determine sublists to render.
+For example, this will produce a nested list of two top level items (`Hello` and `Goodbye`), each with three subitems.
+
+```jsx
+const DATA = [
+    {
+        title: "Hello",
+        children: [
+            { title: "One" },
+            { title: "Two" },
+            { title: "Three" }
+        ]
+    },
+    {
+        title: "Goodbye",
+        children: [
+            { title: "Four" },
+            { title: "Five" },
+            { title: "Six" }
+        ]
+    }
+];
+
+return function View() {
+    return <dc.List rows={DATA} renderer={item => item.title} />;
+}
+```
+
+If you want to use another field instead, you can override the `childSource` property to provide
+either a different property, list of properties, or even an arbitrary function:
+
+```jsx
+return function View() {
+    // Provide an alternative property to use.
+    return <dc.List rows={...} childSource={"items"} ... />;
+    // Provide a list of alternative properties.
+    return <dc.List rows={...} childSource={["items", "things"]} ... />;
+    // Provide an arbitrary function.
+    return <dc.List rows={...} childSource={item => item.value("doodads")} ... />;
+}
+```
+
+You can also control the maximum depth of children to show via `maxChildDepth`; this defaults to
+a small constant (<20) by default.
+
+```jsx
+return function View() {
+    // Show only at most two levels of children.
+    return <dc.List rows={...} childSource={"items"} maxChildDepth={2} ... />;
+}
+```
+
+Children and grouping can be combined to create very interesting views, such as this one which
+dynamically generates a list of books as well as all pages/sections immediately linking to that book:
+
+```jsx
+// Finds all things linked to book that themselves can be linked to.
+function findLinked(book) {
+	return dc.query(`[[${book.$path}]] and $types.econtains("linkable")`);
+}
+
+return function View() {
+    // Groups both by 
+    const books = dc.useQuery("@page and #book");
+    const groupedBooks = dc.useArray(books, array => array.groupBy(book => book.value("genre") ?? "No Genre"));
+
+    return <dc.List rows={groupedBooks} renderer={(book) => book.$link} maxChildDepth={1} childSource={findLinked} />;
+}
+```
 
 ## Full Reference
 
@@ -216,7 +287,7 @@ export interface ListState<T> {
      *
      * If null, child extraction is disabled and no children will be fetched. If undefined, uses the default.
      */
-    childProp?: null | string | string[] | ((row: T) => T[]);
+    childSource?: null | string | string[] | ((row: T) => T[]);
 }
 
 export interface GroupingConfig<T> {

src/api/local-api.tsx

@@ -166,6 +166,26 @@ export class DatacoreLocalApi {
         return this.api.tryEvaluate(expression, variables, sourcePath ?? this.path);
     }
 
+    /** Execute a textual or typed index query, returning all results. */
+    public query(query: string | IndexQuery): Indexable[] {
+        return this.api.query(query);
+    }
+
+    /** Execute a textual or typed index query, returning all results. */
+    public tryQuery(query: string | IndexQuery): Result<Indexable[], string> {
+        return this.api.tryQuery(query);
+    }
+
+    /** Execute a textual or typed index query, returning results plus performance metadata. */
+    public fullquery(query: string | IndexQuery): SearchResult<Indexable> {
+        return this.api.fullquery(query);
+    }
+
+    /** Execute a textual or typed index query, returning results plus performance metadata. */
+    public tryFullQuery(query: string | IndexQuery): Result<SearchResult<Indexable>, string> {
+        return this.api.tryFullQuery(query);
+    }
+
     /////////////
     //  Hooks  //
     /////////////

src/api/ui/views/list.tsx

@@ -58,7 +58,7 @@ export interface ListState<T> {
      *
      * If null, child extraction is disabled and no children will be fetched. If undefined, uses the default.
      */
-    childProp?: null | string | string[] | ((row: T) => T[]);
+    childSource?: null | string | string[] | ((row: T) => T[]);
 }
 
 /**
@@ -104,7 +104,7 @@ export function ListView<T>(props: ListState<T>) {
 
     // Maximum amount of recursion we'll allow when expanding children.
     const maxChildDepth = useMemo(() => props.maxChildDepth ?? 12, [props.maxChildDepth]);
-    const childFunc = useMemo(() => ensureChildrenFunc(props.childProp), [props.childProp]);
+    const childFunc = useMemo(() => ensureChildrenFunc(props.childSource), [props.childSource]);
 
     return (
         <div ref={containerRef} className="datacore-list">
@@ -165,23 +165,14 @@ function ListGroup<T>({
         );
     } else {
         // This is a leaf cluster. Render it directly.
-        if (type === "ordered") {
+        if (type === "ordered" || type === "unordered") {
             return (
                 <HtmlList<T>
-                    type="ordered"
+                    type={type}
                     rows={rows}
                     renderer={renderer}
-                    maxChildDepth={maxChildDepth}
-                    childFunc={childFunc}
-                />
-            );
-        } else if (type === "unordered") {
-            return (
-                <HtmlList<T>
-                    type="unordered"
-                    rows={rows}
-                    renderer={renderer}
-                    maxChildDepth={maxChildDepth}
+                    maxDepth={maxChildDepth}
+                    depth={0}
                     childFunc={childFunc}
                 />
             );
@@ -222,25 +213,28 @@ function HtmlList<T>({
     type,
     rows,
     renderer,
-    maxChildDepth,
+    maxDepth,
+    depth,
     childFunc,
 }: {
     type: "ordered" | "unordered";
     rows: T[];
     renderer: (row: T) => React.ReactNode | Literal;
-    maxChildDepth: number;
+    maxDepth: number;
+    depth: number;
     childFunc: (element: T) => T[];
 }) {
     if (type === "ordered") {
         return (
             <ol className={"datacore-list datacore-list-ordered"}>
                 {rows.map((element, index) => (
                     <HtmlListItem<T>
+                        type={type}
                         element={element}
                         key={index}
                         renderer={renderer}
-                        maxDepth={maxChildDepth}
-                        depth={0}
+                        maxDepth={maxDepth}
+                        depth={depth}
                         childFunc={childFunc}
                     />
                 ))}
@@ -251,11 +245,12 @@ function HtmlList<T>({
             <ul className={"datacore-list datacore-list-unordered"}>
                 {rows.map((element, index) => (
                     <HtmlListItem<T>
+                        type={type}
                         element={element}
                         key={index}
                         renderer={renderer}
-                        maxDepth={maxChildDepth}
-                        depth={0}
+                        maxDepth={maxDepth}
+                        depth={depth}
                         childFunc={childFunc}
                     />
                 ))}
@@ -266,12 +261,14 @@ function HtmlList<T>({
 
 /** A single <li> item (potentially with children) in an HTML list. */
 function HtmlListItem<T>({
+    type,
     element,
     renderer,
     maxDepth,
     depth,
     childFunc,
 }: {
+    type: "ordered" | "unordered";
     element: T;
     renderer: (row: T) => React.ReactNode | Literal;
     maxDepth: number;
@@ -286,16 +283,16 @@ function HtmlListItem<T>({
     return (
         <li className={"datacore-list-item"}>
             {ensureListElement(renderer(element))}
-            {children?.map((child, index) => (
-                <HtmlListItem<T>
-                    element={child}
-                    key={index}
+            {children && (
+                <HtmlList<T>
+                    type={type}
+                    rows={children}
                     maxDepth={maxDepth}
                     depth={depth + 1}
                     renderer={renderer}
                     childFunc={childFunc}
                 />
-            ))}
+            )}
         </li>
     );
 }