vira 28.8.0 → 28.9.0

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.d.ts

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

package/dist/util/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "vira",
-    "version": "28.8.0",
+    "version": "28.9.0",
     "description": "A simple and highly versatile design system using element-vir.",
     "keywords": [
         "design",