vira 28.19.4 → 28.19.6

package/src/util/define-table.ts

@@ -0,0 +1,279 @@
+import {check} from '@augment-vir/assert';
+import {filterMap, type ArrayElement, type PartialWithUndefined} from '@augment-vir/common';
+import {type HtmlInterpolation} from 'element-vir';
+
+/**
+ * An individual key definition in {@link ViraTableHeaders}.
+ *
+ * @category Internal
+ */
+export type ViraTableKey = Readonly<
+    {
+        /** The key that cells must set a value to. */
+        key: string | number;
+    } & PartialWithUndefined<{
+        /** If this is not provided, `key` will be used directly. */
+        content: HtmlInterpolation;
+        /** If set to `true`, this header (and it's column) won't be rendered. */
+        disabled: boolean;
+    }>
+>;
+
+/**
+ * All header definitions for a {@link ViraTable} instance.
+ *
+ * @category Internal
+ */
+export type ViraTableHeaders = ReadonlyArray<ViraTableKey>;
+
+/**
+ * An individual entry in {@link ViraTable}. In default table orientation, this will be a row. In
+ * horizontal orientation, this will be a column.
+ *
+ * @category Internal
+ */
+export type ViraTableEntry<Headers extends ViraTableHeaders | undefined = undefined> = Record<
+    HeaderKey<Headers>,
+    HtmlInterpolation
+>;
+
+/**
+ * An individual cell in {@link ViraTableRow}.
+ *
+ * @category Internal
+ */
+export type ViraTableCell<
+    Headers extends ViraTableHeaders | undefined = undefined,
+    CellData = any,
+> = {
+    content: HtmlInterpolation;
+    key: HeaderKey<Headers>;
+    /**
+     * The original entry that created this row (in default or vertical table orientation) or column
+     * (in horizontal table orientation). This is `undefined` in header cells.
+     */
+    data: CellData;
+};
+
+/**
+ * An individual row in {@link ViraTable}.
+ *
+ * @category Internal
+ */
+export type ViraTableRow<
+    Headers extends ViraTableHeaders | undefined = undefined,
+    CellData = any,
+    RowData = CellData,
+> = {
+    cells: ViraTableCell<Headers, CellData>[];
+    data: RowData;
+};
+
+/**
+ * All keys for the given headers.
+ *
+ * @category Internal
+ */
+export type HeaderKey<Headers extends ViraTableHeaders | undefined = undefined> =
+    undefined extends Headers ? string | number : ArrayElement<Exclude<Headers, undefined>>['key'];
+
+/**
+ * Table information that can easily be mapped into a `<table>` element.
+ *
+ * @category Internal
+ */
+export type ViraTable<
+    Headers extends ViraTableHeaders | undefined = undefined,
+    Orientation extends ViraTableOrientation = ViraTableOrientation.Vertical,
+    OriginalData extends ReadonlyArray<any> = any[],
+> = Orientation extends ViraTableOrientation.Horizontal
+    ? {
+          headerRow: undefined;
+          orientation: Orientation;
+          rows: ViraTableRow<Headers, ArrayElement<OriginalData> | undefined, undefined>[];
+      }
+    : {
+          headerRow: ViraTableCell<Headers, undefined>[];
+          orientation: Orientation;
+          rows: ViraTableRow<Headers, ArrayElement<OriginalData>>[];
+      };
+
+/**
+ * Orientation options for {@link ViraTable}.
+ *
+ * @category Internal
+ */
+export enum ViraTableOrientation {
+    /**
+     * This corresponds to a _vertical_ entry sequence (as you move from entry to entry, you move
+     * across the table vertically). This is the default table layout. Each entry becomes a new row.
+     * Headers are in a separate row.
+     */
+    Vertical = 'vertical',
+    /**
+     * This corresponds to a _horizontal_ entry sequence (as you move from entry to entry, you move
+     * across the table horizontally). Each entry becomes a column. Headers are the left most
+     * column.
+     */
+    Horizontal = 'horizontal',
+}
+
+/**
+ * Options for {@link defineTable}.
+ *
+ * @category Internal
+ */
+export type ViraTableOptions<Orientation extends ViraTableOrientation = ViraTableOrientation> =
+    PartialWithUndefined<{
+        orientation: Orientation;
+        hideHeaders: boolean;
+    }>;
+
+/**
+ * Accepts headers and entries and lays them out into rows according to the given
+ * `options.orientation` (defaulting to vertical). This does not itself create a `<table>` element,
+ * but makes it easy to loop over rows to (with `.map()`) to generate rows in a table.
+ *
+ * @category Table
+ */
+export function defineTable<
+    const Headers extends ViraTableHeaders,
+    OriginalData extends ReadonlyArray<any>,
+    const Orientation extends ViraTableOrientation = ViraTableOrientation.Vertical,
+>(
+    /** The order of these keys determines the order that they render in. */
+    headers: Readonly<Headers>,
+    originalData: OriginalData,
+    dataMap: (
+        entry: ArrayElement<OriginalData>,
+        entryIndex: number,
+    ) => ViraTableEntry<Headers> | undefined,
+    options: ViraTableOptions<Orientation> = {},
+): ViraTable<Headers, Orientation, OriginalData> {
+    const mappedData = originalData.map((dataRow, rowIndex) => {
+        return {
+            cells: dataMap(dataRow, rowIndex) as ViraTableEntry | undefined,
+            data: dataRow,
+        };
+    });
+
+    if (options.orientation === ViraTableOrientation.Horizontal) {
+        const rows: ViraTableRow<Headers, ArrayElement<OriginalData> | undefined, undefined>[] =
+            filterMap(
+                headers,
+                (
+                    header,
+                ):
+                    | ViraTableRow<Headers, ArrayElement<OriginalData> | undefined, undefined>
+                    | undefined => {
+                    if (header.disabled) {
+                        return undefined;
+                    }
+
+                    const headerCellArray: ViraTableCell<Headers>[] = options.hideHeaders
+                        ? []
+                        : [
+                              {
+                                  content: header.content ?? header.key,
+                                  key: header.key,
+                                  data: undefined,
+                              },
+                          ];
+
+                    const cells: ViraTableCell<Headers, ArrayElement<OriginalData>>[] = filterMap(
+                        mappedData,
+                        ({
+                            data,
+                            cells,
+                        }): ViraTableCell<Headers, ArrayElement<OriginalData>> | undefined => {
+                            if (!cells) {
+                                return undefined;
+                            }
+
+                            return {
+                                content: cells[header.key],
+                                key: header.key,
+                                data,
+                            };
+                        },
+                        check.isTruthy,
+                    );
+
+                    const allCells = [
+                        ...headerCellArray,
+                        ...cells,
+                    ];
+
+                    return {
+                        cells: allCells,
+                        data: undefined,
+                    };
+                },
+                check.isTruthy,
+            );
+
+        return {
+            headerRow: undefined,
+            rows,
+            orientation: ViraTableOrientation.Horizontal,
+        } satisfies ViraTable<Headers, ViraTableOrientation.Horizontal> as ViraTable<
+            Headers,
+            Orientation
+        >;
+    } else {
+        const headerRow: ViraTableCell<Headers>[] = options.hideHeaders
+            ? []
+            : filterMap(
+                  headers,
+                  (header): ViraTableCell<Headers> | undefined => {
+                      if (header.disabled) {
+                          return undefined;
+                      }
+
+                      return {
+                          content: header.content ?? header.key,
+                          key: header.key,
+                          data: undefined,
+                      };
+                  },
+                  check.isTruthy,
+              );
+
+        const rows: ViraTableRow<Headers, ArrayElement<OriginalData>>[] = filterMap(
+            mappedData,
+            ({cells, data}): ViraTableRow<Headers, ArrayElement<OriginalData>> | undefined => {
+                if (!cells) {
+                    return undefined;
+                }
+
+                return {
+                    cells: filterMap(
+                        headers,
+                        (
+                            header,
+                        ): ViraTableCell<Headers, ArrayElement<OriginalData>> | undefined => {
+                            if (header.disabled) {
+                                return undefined;
+                            }
+
+                            return {
+                                content: cells[header.key],
+                                key: header.key,
+                                data,
+                            };
+                        },
+                        check.isTruthy,
+                    ),
+                    data,
+                };
+            },
+            check.isTruthy,
+        );
+
+        return {
+            headerRow,
+            rows,
+            orientation: ViraTableOrientation.Vertical,
+        } satisfies ViraTable<Headers> as ViraTable<Headers, Orientation>;
+    }
+}

package/src/util/dynamic-element.ts

@@ -0,0 +1,129 @@
+import {type Values} from '@augment-vir/common';
+import {type AsyncProp, asyncProp, type DeclarativeElementDefinition} from 'element-vir';
+import {type RequireExactlyOne} from 'type-fest';
+
+/**
+ * Base type for loaders passed to {@link createDynamicElementLoader}.
+ *
+ * @category Internal
+ */
+export type BaseDynamicElementLoaders = Record<string, () => Promise<DeclarativeElementDefinition>>;
+
+/**
+ * Create a dynamic element loader. This should go in your element state. This makes deferring
+ * element importing convenient and allows parts of your app to be placed in separate bundles. Make
+ * sure to also use {@link renderDynamicElement} to use the output of this loader.
+ *
+ * @category Util
+ * @see {@link renderDynamicElement}
+ * @see [example usage](https://github.com/electrovir/vira/blob/dev/packages/vira-book/src/element-book/entries/dynamic-elements.book.ts)
+ */
+export function createDynamicElementLoader<
+    const Loaders extends Readonly<BaseDynamicElementLoaders>,
+>(loaders: Readonly<Loaders>): DynamicElementAsyncProp<Loaders> {
+    return asyncProp<DynamicElementValue<NoInfer<Loaders>>, keyof NoInfer<Loaders>>({
+        async updateCallback(elementKey, previousResolvedValue) {
+            if (previousResolvedValue && elementKey in previousResolvedValue.cache) {
+                return {
+                    cache: previousResolvedValue.cache,
+                    element: previousResolvedValue.cache[elementKey],
+                    key: elementKey,
+                };
+            }
+
+            const imported = await loaders[elementKey]();
+
+            return {
+                cache: {
+                    ...previousResolvedValue?.cache,
+                    [elementKey]: imported,
+                },
+                element: imported,
+                key: elementKey,
+            } as any;
+        },
+    });
+}
+
+/**
+ * The value for the async prop {@link DynamicElementAsyncProp}.
+ *
+ * @category Internal
+ */
+export type DynamicElementValue<Loaders extends BaseDynamicElementLoaders> = {
+    cache: Partial<Record<keyof Loaders, DeclarativeElementDefinition>>;
+    element: Awaited<ReturnType<Values<Loaders>>>;
+    key: keyof Loaders;
+};
+/**
+ * An async prop for dynamic loading elements. This is the output from
+ * {@link createDynamicElementLoader}.
+ *
+ * @category Internal
+ */
+export type DynamicElementAsyncProp<Loaders extends BaseDynamicElementLoaders> = AsyncProp<
+    DynamicElementValue<Loaders>,
+    keyof Loaders
+>;
+
+/**
+ * Params for the `ready` callback in {@link renderDynamicElement}.
+ *
+ * @category Internal
+ */
+export type ReadyParams<Loaders extends Readonly<BaseDynamicElementLoaders>> = RequireExactlyOne<{
+    [Key in keyof Loaders]: Awaited<ReturnType<Loaders[Key]>>;
+}>;
+
+/**
+ * Renders the current state of a dynamic element loader. This should go in your render function.
+ * Make sure to also use {@link createDynamicElementLoader} to create a dynamic loader in your
+ * element's state.
+ *
+ * @category Util
+ * @see {@link createDynamicElementLoader}
+ * @see [example usage](https://github.com/electrovir/vira/blob/dev/packages/vira-book/src/element-book/entries/dynamic-elements.book.ts)
+ */
+export function renderDynamicElement<
+    const Loaders extends BaseDynamicElementLoaders,
+    const LoadingReturnValue,
+    const ReadyReturnValue,
+    const ErrorReturnValue,
+>(
+    asyncProp: DynamicElementAsyncProp<Loaders>,
+    {
+        ready,
+        loading,
+        error,
+        key,
+    }: {
+        /**
+         * If this is left undefined (or falsy), the current key will not be set, whatever the
+         * existing key is will continue to be used.
+         */
+        key?: keyof NoInfer<Loaders> | undefined;
+        loading(this: void, params: Promise<ReadyParams<NoInfer<Loaders>>>): LoadingReturnValue;
+        ready(this: void, params: ReadyParams<NoInfer<Loaders>>): ReadyReturnValue;
+        error(this: void, error: Error): ErrorReturnValue;
+    },
+): ReadyReturnValue | LoadingReturnValue | ErrorReturnValue {
+    if (key) {
+        (asyncProp.update as (key: keyof Loaders) => boolean)(key);
+    }
+
+    if (asyncProp.value instanceof Error) {
+        return error(asyncProp.value);
+    } else if (asyncProp.value instanceof Promise) {
+        return loading(
+            asyncProp.value.then((value) => {
+                return {
+                    [value.key]: value.element,
+                } as ReadyParams<Loaders>;
+            }),
+        );
+    } else {
+        return ready({
+            [asyncProp.value.key]: asyncProp.value.element,
+        } as ReadyParams<Loaders>);
+    }
+}