Merge branch 'list-view'

Author: blacksmithgu

docs/docs/code-views/data-array.md

@@ -0,0 +1,169 @@
+---
+title: Data Arrays
+sidebar_label: Data Arrays
+sidebar_position: 500
+---
+
+To make common data manipuation operations simple, datacore provides the `DataArray` abstraction, which is a [proxied](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) wrapper around a regular list with a large set of additional functions.
+
+## Creation
+
+Data arrays are mainly present in two places.
+
+### Via `dc.useArray`
+
+The most common route for using data arrays is the `dc.useArray` hook, which takes in a regular array
+of data, converts it to a data array, performs operations on it, and then converts it back to a regular array:
+
+```js
+return function View() {
+    // Start with some data you want to process...
+    const books = dc.useQuery("#books and @page");
+    // Use `dc.useArray` to get a data array for processing.
+    const groupedBooks = dc.useArray(books, array =>
+        array.sort(book => book.$name)
+             .groupBy(book => book.value("genre")));
+
+    // Then render it.
+    return <dc.List rows={groupedBooks} />;
+}
+```
+
+### Via `dc.array`
+
+You can also directly make `DataArray`s via the utility function `dc.array(data)`, which accepts a
+regular array as input and produces a data array.
+
+```js
+return function View() {
+    // da is a `DataArray`.
+    const da = dc.array([1, 2, 3]);
+    // da2 is still a `DataArray`.
+    const da2 = da.map(x => x + 4).limit(2);
+
+    // To get a regular array back, use `.array()`.
+    const data = da2.array();
+}
+```
+
+## Indexing and Swizzling
+
+Data arrays support regular indexing just like normal arrays (like `array[0]`), but importantly, they also support
+query-language-style "swizzling": if you index into a data array with a field name (like `array.field`), it
+automatically maps every element in the array to `field`, flattening `field` if it itself is also an array.
+
+```js
+const data = dc.array(dc.query("#books and @page"));
+
+data.$name // => List of all book names.
+data.$ctime // => List of all book created times.
+```
+
+## Raw Interface
+
+The full interface for the data array implementation is provided below for reference:
+
+```ts
+/** A function which maps an array element to some value. */
+export type ArrayFunc<T, O> = (elem: T, index: number, arr: T[]) => O;
+
+/** A function which compares two types. */
+export type ArrayComparator<T> = (a: T, b: T) => number;
+
+/**
+ * Proxied interface which allows manipulating array-based data. All functions on a data array produce a NEW array
+ * (i.e., the arrays are immutable).
+ */
+export interface DataArray<T> {
+    /** The total number of elements in the array. */
+    length: number;
+
+    /** Filter the data array down to just elements which match the given predicate. */
+    where(predicate: ArrayFunc<T, boolean>): DataArray<T>;
+    /** Alias for 'where' for people who want array semantics. */
+    filter(predicate: ArrayFunc<T, boolean>): DataArray<T>;
+
+    /** Map elements in the data array by applying a function to each. */
+    map<U>(f: ArrayFunc<T, U>): DataArray<U>;
+    /** Map elements in the data array by applying a function to each, then flatten the results to produce a new array. */
+    flatMap<U>(f: ArrayFunc<T, U[]>): DataArray<U>;
+    /** Mutably change each value in the array, returning the same array which you can further chain off of. */
+    mutate(f: ArrayFunc<T, any>): DataArray<any>;
+
+    /** Limit the total number of entries in the array to the given value. */
+    limit(count: number): DataArray<T>;
+    /**
+     * Take a slice of the array. If `start` is undefined, it is assumed to be 0; if `end` is undefined, it is assumed
+     * to be the end of the array.
+     */
+    slice(start?: number, end?: number): DataArray<T>;
+    /** Concatenate the values in this data array with those of another iterable / data array / array. */
+    concat(other: Iterable<T>): DataArray<T>;
+
+    /** Return the first index of the given (optionally starting the search) */
+    indexOf(element: T, fromIndex?: number): number;
+    /** Return the first element that satisfies the given predicate. */
+    find(pred: ArrayFunc<T, boolean>): T | undefined;
+    /** Find the index of the first element that satisfies the given predicate. Returns -1 if nothing was found. */
+    findIndex(pred: ArrayFunc<T, boolean>, fromIndex?: number): number;
+    /** Returns true if the array contains the given element, and false otherwise. */
+    includes(element: T): boolean;
+
+    /**
+     * Return a string obtained by converting each element in the array to a string, and joining it with the
+     * given separator (which defaults to ', ').
+     */
+    join(sep?: string): string;
+
+    /**
+     * Return a sorted array sorted by the given key; an optional comparator can be provided, which will
+     * be used to compare the keys in leiu of the default dataview comparator.
+     */
+    sort<U>(key: ArrayFunc<T, U>, direction?: "asc" | "desc", comparator?: ArrayComparator<U>): DataArray<T>;
+
+    /**
+     * Return an array where elements are grouped by the given key; the resulting array will have objects of the form
+     * { key: <key value>, rows: DataArray }.
+     */
+    groupBy<U>(key: ArrayFunc<T, U>, comparator?: ArrayComparator<U>): DataArray<{ key: U; rows: DataArray<T> }>;
+
+    /**
+     * Return distinct entries. If a key is provided, then rows with distinct keys are returned.
+     */
+    distinct<U>(key?: ArrayFunc<T, U>, comparator?: ArrayComparator<U>): DataArray<T>;
+
+    /** Return true if the predicate is true for all values. */
+    every(f: ArrayFunc<T, boolean>): boolean;
+    /** Return true if the predicate is true for at least one value. */
+    some(f: ArrayFunc<T, boolean>): boolean;
+    /** Return true if the predicate is FALSE for all values. */
+    none(f: ArrayFunc<T, boolean>): boolean;
+
+    /** Return the first element in the data array. Returns undefined if the array is empty. */
+    first(): T;
+    /** Return the last element in the data array. Returns undefined if the array is empty. */
+    last(): T;
+
+    /** Map every element in this data array to the given key, and then flatten it.*/
+    to(key: string): DataArray<any>;
+    /**
+     * Recursively expand the given key, flattening a tree structure based on the key into a flat array. Useful for handling
+     * hierarchical data like tasks with 'subtasks'.
+     */
+    expand(key: string): DataArray<any>;
+
+    /** Run a lambda on each element in the array. */
+    forEach(f: ArrayFunc<T, void>): void;
+
+    /** Convert this to a plain javascript array. */
+    array(): T[];
+
+    /** Allow iterating directly over the array. */
+    [Symbol.iterator](): Iterator<T>;
+
+    /** Map indexes to values. */
+    [index: number]: any;
+    /** Automatic flattening of fields. Equivalent to implicitly calling `array.to("field")` */
+    [field: string]: any;
+}
+```

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

@@ -0,0 +1,226 @@
+---
+title: List Views (dc.List)
+sidebar_label: List Views
+sidebar_position: 100
+---
+
+List views, available as `dc.List`, generate pageable lists of results. They support grouping, heirarchies, paging, and several view modes. They come in three varieties:
+
+- **Unordered** (`unordered`): A bullet-point style list.
+- **Ordered** (`ordered`): A numbered list of items.
+- **Block**: (`block`): A list with no additional formatting - just shows elements in a vertical list of 'blocks'.
+
+## Quickstart
+
+Most common usages of lists will use `rows` and `renderer`:
+
+```jsx
+return function View() {
+    // Start by fetching your data via a query.
+    const data = dc.useQuery("#book and @page");
+
+    // Pass the full data to `rows`, and specify what to show in the list via `renderer`:
+    return <dc.List rows={data} renderer={book => book.$link} />;
+}
+```
+
+Lists are also commonly used for rendering embeds:
+
+```jsx
+return function View() {
+    const data = dc.useQuery("#important-note and @block");
+
+    // Uses `dc.embed` to render an embed of all of the given blocks, with paging for performnace.
+    return <dc.List rows={data} paging={true} renderer={dc.embed} />;
+}
+```
+
+For the full set of available options, read on.
+
+## Basic Usage (`rows`)
+
+The list view is available in the local API as `dc.List`; it at a minimum requires a list of elements to show (`rows`):
+
+```js
+const ITEMS = ["First", "Second", "Third"];
+
+return function View() {
+    return <dc.List rows={ITEMS} />;
+}
+```
+
+Which will produce a simple list like so:
+
+- First
+- Second
+- Third
+
+### List Types (`type`)
+
+You can control which of the list types you want via the `type` property.
+
+```js
+const ITEMS = ["First", "Second", "Third"];
+
+return function View() {
+    return <dc.List type="ordered" rows={ITEMS} />;
+}
+```
+
+The three options available are:
+
+- **Unordered** (`unordered`): A bullet-point style list. This is the default.
+- **Ordered** (`ordered`): A numbered list of items. Numbering starts at 1 and increments.
+- **Block**: (`block`): A list with no additional formatting - just shows elements in a vertical list of 'blocks'.
+    - Block formatting is best for embeds or other use cases where you do not want visible formatting from a regular list.
+
+### Specifying How To Render Data (`renderer`)
+
+When working with queries and any other non-trivial object, you will likely want to specify exactly what to render and how. This can be done via the `renderer` prop, which accepts a function that maps
+each row to the value or JSX to render.
+
+```jsx
+return function View() {
+    // This will give back a set of MarkdownPage objects, which are not useful to render on their own.
+    const books = dc.useQuery("#book and @page");
+
+    // Render books by rendering their links.
+    return <dc.List rows={books} renderer={book => book.$link} />;
+}
+```
+
+Some built-in rendering functions already exist, such as `dc.embed`, which renders embeds of files
+automatically:
+
+```jsx
+return function View() {
+    // Fetch all blocks referencing a specific tag.
+    const notes = dc.useQuery("#life-notes and @block");
+
+    // Render the notes as embeds in block format for minimal formatting.
+    return <dc.List type="block" rows={notes} renderer={dc.embed} />;
+}
+```
+
+### Paging (`paging` / `scrollOnPaging`)
+
+You can add paging to any list using the `paging` prop, which accepts several options.
+
+```js
+// Explicitly disable paging.
+<dc.List paging={false} ... />
+
+// Enable paging, with the page size equal to your default page size in the Datacore settings.
+<dc.List paging={true} ... />
+
+// Enable paging with the specific page size.
+<dc.List paging={10} ... />
+```
+
+If `paging` is not specified, it defaults to whatever your default paging configuration is in
+the Datacore settings.
+
+### Grouping (`groupings`)
+
+List views automatically support rendering grouped data; grouped data can be created most easily
+using [Data Array](data-array) syntax.
+
+```jsx
+return function View() {
+    // Fetch all books and then group them by genre.
+    const books = dc.useQuery("#book and @page");
+    const booksByGenre = dc.useArray(books, array => array.groupBy(book => book.value("genre")));
+
+    // No extra configuration is required by default to show groups.
+    return <dc.List rows={booksByGenre} renderer={book => book.$link} />;
+}
+```
+
+By default, grouped data will render the grouping headers using the default text renderer. If you'd
+like to add embellishments, such as converting each of the 'genres' in the above examples into links,
+you can use the `groupings` prop:
+
+```jsx
+return function View() {
+    // Fetch all books and then group them by genre.
+    const books = dc.useQuery("#book and @page");
+    const booksByGenre = dc.useArray(books, array => array.groupBy(book => book.value("genre")));
+
+    // Render each grouping key as a file link instead of just text.
+    return <dc.List rows={booksByGenre} renderer={book => book.$link} groupings={(key) => dc.fileLink(key)} />;
+}
+```
+
+You can also choose to construct an explicit `GroupingConfig` instead of passing a function:
+
+```jsx
+const LINK_GROUPING = {
+    render: (key, rows) => dc.fileLink(key)
+};
+
+return function View() {
+    // Fetch all books and then group them by genre.
+    const books = dc.useQuery("#book and @page");
+    const booksByGenre = dc.useArray(books, array => array.groupBy(book => book.value("genre")));
+
+    // Render each grouping key as a file link instead of just text.
+    return <dc.List rows={booksByGenre} renderer={book => book.$link} groupings={LINK_GROUPING} />;
+}
+```
+
+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`)
+
+## Full Reference
+
+The full set of available properties is provided below:
+
+```js
+export interface ListState<T> {
+    /**
+     * Whether the list should be ordered, unordered, or block.
+     *
+     * Block lists do not use an actual list element and instead just render a series of contiguous
+     * div elements with no other annotations.
+     */
+    type?: "ordered" | "unordered" | "block";
+
+    /** The full collection of elements in the list. */
+    rows: Grouping<T>;
+
+    /** Allows for grouping header lines to be overridden with custom rendering/logic. */
+    groupings?: GroupingConfig<T> | GroupingConfig<T>[] | ((key: Literal, rows: Grouping<T>) => Literal | VNode);
+
+    /**
+     * Custom render function to use for rendering each leaf element. Can produce either JSX or a plain value which will be
+     * rendered as a literal.
+     */
+    renderer?: (row: T) => React.ReactNode | Literal;
+
+    /** Controls whether paging is enabled for this element. If true, uses default page size. If a number, paging is enabled with the given page size. */
+    paging?: boolean | number;
+
+    /**
+     * Whether the view will scroll to the top automatically on page changes. If true, will always scroll on page changes.
+     * If a number, will scroll only if the number is greater than the current page size.
+     **/
+    scrollOnPaging?: boolean | number;
+
+    /** Maximum level of children that will be rendered; a level of 0 means no children expansion will occur. */
+    maxChildDepth?: number;
+
+    /**
+     * Property name, list of property names, or function to be applied to obtain children for a given entry.
+     * Defaults to the `$children` and `children` props.
+     *
+     * If null, child extraction is disabled and no children will be fetched. If undefined, uses the default.
+     */
+    childProp?: null | string | string[] | ((row: T) => T[]);
+}
+
+export interface GroupingConfig<T> {
+    /** How a grouping with the given key and set of rows should be rendered. */
+    render?: (key: Literal, rows: Grouping<T>) => Literal | VNode;
+}
+```