vira 32.0.0-beta.0 → 32.1.0

package/src/util/define-table.ts

@@ -1,286 +0,0 @@
-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,
-        originalData,
-        dataMap,
-        options = {},
-    }: Readonly<{
-        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/define-vira-element.ts

@@ -1,29 +0,0 @@
-import {wrapDefineElement} from 'element-vir';
-
-/**
- * Required prefix for all vira elements.
- *
- * @category Internal
- */
-export const ViraTagNamePrefix = 'vira-';
-/**
- * Required tag name for all vira elements. This includes {@link ViraTagNamePrefix} in it.
- *
- * @category Internal
- */
-export type ViraTagName = `${typeof ViraTagNamePrefix}${string}`;
-
-/**
- * Define a vira element with custom requirements (like the `vira-` element tag prefix).
- *
- * @category Internal
- */
-export const defineViraElement = wrapDefineElement<ViraTagName>({
-    assertInputs: (inputs) => {
-        if (!inputs.tagName.startsWith(ViraTagNamePrefix)) {
-            throw new Error(
-                `Tag name should start with '${ViraTagNamePrefix}' but got '${inputs.tagName}'`,
-            );
-        }
-    },
-});

package/src/util/dynamic-element.ts

@@ -1,128 +0,0 @@
-import {type RequireExactlyOne, type Values} from '@augment-vir/common';
-import {type AsyncProp, asyncProp, type DeclarativeElementDefinition} from 'element-vir';
-
-/**
- * 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>);
-    }
-}

package/src/util/pop-up-helpers.ts

@@ -1,133 +0,0 @@
-import {
-    filterMap,
-    joinWithFinalConjunction,
-    type MaybePromise,
-    type PartialWithUndefined,
-} from '@augment-vir/common';
-import {html, listen, type HtmlInterpolation} from 'element-vir';
-import {ViraMenuItem} from '../elements/pop-up/vira-menu-item.element.js';
-import {
-    type PopUpManager,
-    type PopUpManagerOptions,
-    type ShowPopUpResult,
-} from './pop-up-manager.js';
-
-/**
- * Verifies that all items have unique ids.
- *
- * @category Internal
- */
-export function assertUniqueIdProps(items: ReadonlyArray<Readonly<{id: PropertyKey}>>) {
-    const usedIds = new Set<PropertyKey>();
-    const duplicateIds: PropertyKey[] = [];
-    items.forEach((option) => {
-        if (usedIds.has(option.id)) {
-            duplicateIds.push(option.id);
-        } else {
-            usedIds.add(option.id);
-        }
-    });
-
-    if (duplicateIds.length) {
-        throw new Error(
-            `Duplicate option ids were given: ${joinWithFinalConjunction(duplicateIds)}`,
-        );
-    }
-}
-
-/**
- * Handles toggling pop up state for `ViraDropdown`.
- *
- * @category Internal
- */
-export function triggerPopUpState({
-    open,
-    callback,
-    popUpManager,
-    host,
-    options,
-}: Readonly<
-    {
-        open: boolean;
-        popUpManager: PopUpManager;
-        host: HTMLElement;
-    } & PartialWithUndefined<{
-        callback?: ((showPopUpResult: ShowPopUpResult | undefined) => void) | undefined;
-        options?: Partial<PopUpManagerOptions> | undefined;
-    }>
->) {
-    if (open) {
-        const showPopUpResult = popUpManager.showPopUp(host, options);
-        callback?.(showPopUpResult);
-    } else {
-        popUpManager.removePopUp();
-        callback?.(undefined);
-    }
-}
-
-/**
- * A helper type to be used with {@link renderMenuItemEntries}.
- *
- * @category PopUp
- */
-export type ViraMenuItemEntry = {
-    content: HtmlInterpolation;
-} & PartialWithUndefined<{
-    selected: boolean;
-    /** Called when any item is activated. */
-    onClick: MenuItemClickCallback;
-    /**
-     * If set to `true`, this menu item won't show up at all.
-     *
-     * @default false
-     */
-    hidden: boolean;
-}> &
-    typeof ViraMenuItem.InputsType;
-
-/**
- * A callback for menu items getting activated, to be used with {@link renderMenuItemEntries}.
- *
- * @category PopUp
- */
-export type MenuItemClickCallback = (
-    params: Readonly<{
-        /** The menu item's index in the array. */
-        index: number;
-        event: MouseEvent;
-    }>,
-) => MaybePromise<void>;
-
-/**
- * A helper for rendering a bunch of menu items.
- *
- * @category PopUp
- */
-export function renderMenuItemEntries(items: ReadonlyArray<Readonly<ViraMenuItemEntry>>) {
-    return filterMap(
-        items,
-        (item, index) => {
-            return html`
-                <${ViraMenuItem.assign({
-                    ...item,
-                })}
-                    ${listen('click', async (event) => {
-                        if (item.disabled) {
-                            event.stopImmediatePropagation();
-                            event.preventDefault();
-                            return;
-                        }
-
-                        await item.onClick?.({
-                            event,
-                            index,
-                        });
-                    })}
-                >
-                    ${item.content}
-                </${ViraMenuItem}>
-            `;
-        },
-        (template, menuItem) => !menuItem.hidden,
-    );
-}