vira 28.19.6 → 28.20.0

package/dist/util/define-table.d.ts

@@ -0,0 +1,110 @@
+import { 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 declare 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 declare 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>;

package/dist/util/define-table.js

@@ -0,0 +1,115 @@
+import { check } from '@augment-vir/assert';
+import { filterMap } from '@augment-vir/common';
+/**
+ * Orientation options for {@link ViraTable}.
+ *
+ * @category Internal
+ */
+export var ViraTableOrientation;
+(function (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.
+     */
+    ViraTableOrientation["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.
+     */
+    ViraTableOrientation["Horizontal"] = "horizontal";
+})(ViraTableOrientation || (ViraTableOrientation = {}));
+/**
+ * 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(
+/** The order of these keys determines the order that they render in. */
+headers, originalData, dataMap, options = {}) {
+    const mappedData = originalData.map((dataRow, rowIndex) => {
+        return {
+            cells: dataMap(dataRow, rowIndex),
+            data: dataRow,
+        };
+    });
+    if (options.orientation === ViraTableOrientation.Horizontal) {
+        const rows = filterMap(headers, (header) => {
+            if (header.disabled) {
+                return undefined;
+            }
+            const headerCellArray = options.hideHeaders
+                ? []
+                : [
+                    {
+                        content: header.content ?? header.key,
+                        key: header.key,
+                        data: undefined,
+                    },
+                ];
+            const cells = filterMap(mappedData, ({ data, cells, }) => {
+                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,
+        };
+    }
+    else {
+        const headerRow = options.hideHeaders
+            ? []
+            : filterMap(headers, (header) => {
+                if (header.disabled) {
+                    return undefined;
+                }
+                return {
+                    content: header.content ?? header.key,
+                    key: header.key,
+                    data: undefined,
+                };
+            }, check.isTruthy);
+        const rows = filterMap(mappedData, ({ cells, data }) => {
+            if (!cells) {
+                return undefined;
+            }
+            return {
+                cells: filterMap(headers, (header) => {
+                    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,
+        };
+    }
+}

package/dist/util/dynamic-element.d.ts

@@ -0,0 +1,63 @@
+import { type Values } from '@augment-vir/common';
+import { type 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 declare function createDynamicElementLoader<const Loaders extends Readonly<BaseDynamicElementLoaders>>(loaders: Readonly<Loaders>): DynamicElementAsyncProp<Loaders>;
+/**
+ * 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 declare 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;

package/dist/util/dynamic-element.js

@@ -0,0 +1,61 @@
+import { asyncProp } from 'element-vir';
+/**
+ * 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(loaders) {
+    return asyncProp({
+        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,
+            };
+        },
+    });
+}
+/**
+ * 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(asyncProp, { ready, loading, error, key, }) {
+    if (key) {
+        asyncProp.update(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,
+            };
+        }));
+    }
+    else {
+        return ready({
+            [asyncProp.value.key]: asyncProp.value.element,
+        });
+    }
+}

package/dist/util/index.js

@@ -0,0 +1,3 @@
+export * from './define-table.js';
+export * from './dynamic-element.js';
+export * from './pop-up-manager.js';

package/dist/util/pop-up-manager.d.ts

@@ -0,0 +1,186 @@
+import { type MaybePromise } from '@augment-vir/common';
+import { type Coords, type NavController } from 'device-navigation';
+import { type ExtractEventByType, type ExtractEventTypes, type ListenOptions, type RemoveListenerCallback } from 'typed-event-target';
+/**
+ * Used to prevent pop-ups from closing when a text input is active.
+ *
+ * @category Internal
+ */
+export declare function isInputLikeElement(element: Element): boolean;
+/**
+ * A type used for representing a rectangle's position.
+ *
+ * @category Internal
+ */
+export type PositionRect = {
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+};
+/**
+ * The default empty {@link PositionRect}, with all values set to 0.
+ *
+ * @category Internal
+ */
+export declare const emptyPositionRect: PositionRect;
+/**
+ * Options for {@link PopUpManager}.
+ *
+ * @category PopUp
+ */
+export type PopUpManagerOptions = {
+    /**
+     * The minimum number of pixels for allowing the pop-up to go downwards. If the downward
+     * available space is less than this, and if the upwards available space is
+     * `verticalDiffThreshold` more than the downwards space, the pop-up will be directed upwards.
+     *
+     * Equation:
+     *
+     *     const directUpwards =
+     *         downwardsSpace < minDownSpace &&
+     *         upwardsSpace > DownwardsSpace + verticalDiffThreshold;
+     *
+     * @default 200
+     */
+    minDownSpace: number;
+    /**
+     * The minimum number of pixels for allowing the pop-up to go rightwards. If the rightward
+     * available space is less than this, and if the leftwards available space is
+     * `horizontalDiffThreshold` more than the rightwards space, the pop-up will be directed
+     * leftwards.
+     *
+     * Equation:
+     *
+     *     const directLeftwards =
+     *         rightwardsSpace < minRightSpace &&
+     *         leftwardsSpace > rightwardsSpace + horizontalDiffThreshold;
+     *
+     * @default 400
+     */
+    minRightSpace: number;
+    /**
+     * The number of pixels required for the upwards available space to be bigger than the downwards
+     * available space before directing the pop-up upwards.
+     *
+     * Equation:
+     *
+     *     const directUpwards =
+     *         downwardsSpace < minDownSpace &&
+     *         upwardsSpace > DownwardsSpace + verticalDiffThreshold;
+     *
+     * @default 20
+     */
+    verticalDiffThreshold: number;
+    /**
+     * The number of pixels required for the leftwards available space to be bigger than the
+     * rightwards available space before directing the pop-up leftwards.
+     *
+     * Equation:
+     *
+     *     const directLeftwards =
+     *         rightwardsSpace < minRightSpace &&
+     *         leftwardsSpace > rightwardsSpace + horizontalDiffThreshold;
+     *
+     * @default 100
+     */
+    horizontalDiffThreshold: number;
+    /**
+     * Supports navigation of the pop up via the `device-navigation` package.
+     *
+     * @default true
+     */
+    supportNavigation: boolean;
+};
+/**
+ * Output type from `PopUpManager.showPopUp`
+ *
+ * @category PopUp
+ */
+export type ShowPopUpResult = {
+    /**
+     * Indicates if the "pop up" should pop in the downwards direction or not. If not, it should pop
+     * in the upwards direction. This is determined by how much space is available on either side of
+     * the root element.
+     */
+    popDown: boolean;
+    /**
+     * Indicates if the "pop up" should pop in the rightwards direction or not. If not, it should
+     * pop in the leftwards direction. This is determined by how much space is available on either
+     * side of the root element.
+     */
+    popRight: boolean;
+    positions: Record<'root' | 'container' | 'diff', PositionRect>;
+};
+declare const HidePopUpEvent_base: (new (eventInitDict?: EventInit) => import("typed-event-target").TypedEvent<"hide-pop-up">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedEvent<"hide-pop-up">, "type">;
+/**
+ * An event fired from {@link PopUpManager} when the pop up should be hidden.
+ *
+ * @category PopUp
+ */
+export declare class HidePopUpEvent extends HidePopUpEvent_base {
+}
+declare const NavSelectEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: Coords;
+}) => import("typed-event-target").TypedCustomEvent<Coords, "nav-select">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<Coords, "nav-select">, "type">;
+/**
+ * An event fired from {@link PopUpManager} when an individual item in the pop up has been selected
+ * by the user.
+ *
+ * @category PopUp
+ */
+export declare class NavSelectEvent extends NavSelectEvent_base {
+}
+/**
+ * All events that can be emitted by {@link PopUpManager}.
+ *
+ * @category Internal
+ */
+export type PopUpManagerEvents = HidePopUpEvent | NavSelectEvent;
+/**
+ * A "pop up" manager for items that pop up from the HTML page, like dropdowns or menus.
+ *
+ * @category PopUp
+ */
+export declare class PopUpManager {
+    readonly navController: NavController;
+    private listenTarget;
+    options: PopUpManagerOptions;
+    private cleanupCallbacks;
+    private lastRootElement;
+    constructor(navController: NavController, options?: Partial<PopUpManagerOptions> | undefined);
+    private attachGlobalListeners;
+    /** Listen to events emitted from a {@link PopUpManager} instance. */
+    listen<const EventDefinition extends Readonly<{
+        type: ExtractEventTypes<PopUpManagerEvents>;
+    }>>(event: EventDefinition, listener: (event: ExtractEventByType<PopUpManagerEvents, EventDefinition['type']>) => MaybePromise<void>, options?: ListenOptions | undefined): RemoveListenerCallback;
+    /** Trigger removal or hiding of the pop up. */
+    removePopUp(): void;
+    /** Trigger showing the pop up. */
+    showPopUp(rootElement: HTMLElement, options?: Partial<PopUpManagerOptions> | undefined): ShowPopUpResult;
+    /**
+     * Cleanup and destroy the {@link PopUpManager} instance. This:
+     *
+     * - Removes the existing pop up
+     * - Cleans up all internal and external listeners
+     */
+    destroy(): void;
+}
+export {};