@adobe/uix-core 0.6.3

package/src/debug-emitter.ts

@@ -0,0 +1,83 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import { _customConsole, DebugLogger, Theme } from "./debuglog.js";
+import { Emits, Unsubscriber } from "./types.js";
+
+/**
+ * Adds methods for logging events
+ * @internal
+ */
+export interface EmitterDebugLogger extends DebugLogger {
+  /**
+   * Listen to an event and pass the logger to the handler
+   * @internal
+   */
+  listen(
+    type: string,
+    listener: (logger: EmitterDebugLogger, ev: CustomEvent) => unknown
+  ): this;
+}
+
+/**
+ * Debugger for EventTarget objects like Hosts, Ports and Guests, which
+ * patches dispatchEvent to log events
+ * Adapter to attach console logging listeners to all events on an emitter.
+ * @internal
+ */
+export function debugEmitter(
+  emitter: Emits,
+  opts: {
+    theme: Theme;
+    type?: string;
+    id?: string;
+  }
+): EmitterDebugLogger {
+  const logger = _customConsole(
+    opts.theme,
+    opts.type ||
+      (Object.getPrototypeOf(emitter) as typeof emitter).constructor.name,
+    opts.id || emitter.id
+  ) as EmitterDebugLogger;
+  const oldDispatch = emitter.dispatchEvent;
+  emitter.dispatchEvent = (event) => {
+    logger.pushState({ type: "event", name: event.type });
+    const retVal = oldDispatch.call(emitter, event) as boolean;
+    logger.popState();
+    return retVal;
+  };
+
+  const subscriptions: Unsubscriber[] = [];
+
+  const oldDetach = logger.detach;
+  logger.detach = () => {
+    oldDetach.call(logger);
+    subscriptions.forEach((unsubscribe) => unsubscribe());
+  };
+
+  /**
+   * Listens and passes a logger to callbacks
+   */
+  function listen(
+    type: string,
+    listener: (logger: EmitterDebugLogger, ev: CustomEvent) => unknown
+  ) {
+    subscriptions.push(
+      emitter.addEventListener(type, (event) => listener(logger, event))
+    );
+    return logger;
+  }
+
+  logger.listen = listen;
+
+  return logger;
+}

package/src/debuglog.ts

@@ -0,0 +1,284 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/**
+ * Fancy looking console decorator.
+ * @hidden
+ * @internal
+ */
+
+/** @internal */
+const isDarkMode = () =>
+  typeof window.matchMedia === "function" &&
+  window.matchMedia("(prefers-color-scheme: dark)").matches;
+
+/** @internal */
+type Layout = {
+  padX: number;
+  padY: number;
+  rounded: number;
+  fontSize: number;
+  emphasis: Style;
+};
+/** @internal */
+type HexColor = `#${string}` | "transparent";
+/** @internal */
+type Color = {
+  text: HexColor;
+  bg: HexColor;
+  hilight: HexColor;
+  shadow: HexColor;
+};
+/** @internal */
+type ThemeSpec = Color & Layout;
+
+/** @internal */
+const Layouts: Record<string, Layout> = {
+  medium: {
+    padX: 5,
+    padY: 3,
+    rounded: 4,
+    fontSize: 100,
+    emphasis: "font-weight: bold;",
+  },
+  small: {
+    padX: 3,
+    padY: 1,
+    rounded: 2,
+    fontSize: 95,
+    emphasis: "font-style: italic;",
+  },
+};
+
+/** @internal */
+const Colors: Record<string, Color> = {
+  yellow: {
+    text: "#333333",
+    bg: "#EBD932",
+    hilight: "#F7E434",
+    shadow: "#D1C12C",
+  },
+  green: {
+    text: "#333333",
+    bg: "#96EB5E",
+    hilight: "#9EF763",
+    shadow: "#85D154",
+  },
+  blue: {
+    text: "#333333",
+    bg: "#8DD0EB",
+    hilight: "#88F0F7",
+    shadow: "#74AED4",
+  },
+  gray: isDarkMode()
+    ? {
+        text: "#eeeeee",
+        bg: "transparent",
+        hilight: "#cecece",
+        shadow: "#cecece",
+      }
+    : {
+        text: "#333333",
+        bg: "#eeeeee",
+        hilight: "#f6f6f6",
+        shadow: "#cecece",
+      },
+};
+
+/** @internal */
+type ThemeTag = `${keyof typeof Colors} ${keyof typeof Layouts}`;
+
+/**
+ * @internal
+ */
+export type Theme = ThemeSpec | ThemeTag;
+
+/** @internal */
+type LogDecorator = (...args: unknown[]) => unknown[];
+
+/** @internal */
+type Style = `${string};`;
+
+function memoizeUnary<T, U>(fn: (arg: T) => U): typeof fn {
+  const cache: Map<T, U> = new Map();
+  return (arg) => {
+    if (!cache.has(arg)) {
+      const result = fn(arg);
+      cache.set(arg, result);
+      if (cache.size > 100) {
+        cache.delete(cache.keys().next().value as T);
+      }
+      return result;
+    }
+    return cache.get(arg);
+  };
+}
+
+const toTheme = memoizeUnary((theme: Theme): ThemeSpec => {
+  if (typeof theme === "string") {
+    const [color, size] = theme.split(" ");
+    return {
+      ...Colors[color],
+      ...Layouts[size],
+    };
+  }
+  return theme;
+});
+
+const block: Style = `display: inline-block; border: 1px solid;`;
+
+const flatten = (side: "left" | "right"): Style =>
+  `padding-${side}: 0px; border-${side}-width: 0px; border-top-${side}-radius: 0px; border-bottom-${side}-radius: 0px;`;
+
+const toColor = ({ bg, hilight, shadow, text }: Color): Style =>
+  `color: ${text}; background: ${bg}; border-color: ${hilight} ${shadow} ${shadow} ${hilight};`;
+
+const toLayout = ({ fontSize, padY, padX, rounded }: Layout) =>
+  `font-size: ${fontSize}%; padding: ${padY}px ${padX}px; border-radius: ${rounded}px;`;
+
+const toBubbleStyle = memoizeUnary((theme: ThemeSpec): string[] => {
+  const base = `${block}${toColor(theme)}${toLayout(theme)}`;
+  return [
+    `${base}${flatten("right")}`,
+    `${base}${flatten("left")}${theme.emphasis}`,
+  ] as Style[];
+});
+
+function toBubblePrepender(
+  bubbleLeft: string,
+  bubbleRight: string,
+  theme: ThemeSpec
+): LogDecorator {
+  const prefix = `%c${bubbleLeft}%c ${bubbleRight}`;
+  const [left, right] = toBubbleStyle(theme);
+  return (args: unknown[]) => {
+    const bubbleArgs = [prefix, left, right];
+    if (typeof args[0] === "string") {
+      bubbleArgs[0] = `${prefix}%c ${args.shift() as string}`;
+      bubbleArgs.push(""); // reset style
+    }
+    return [...bubbleArgs, ...args];
+  };
+}
+
+/** @internal */
+const stateTypes = {
+  event: "️⚡️",
+} as const;
+
+const stateDelim = " ⤻ ";
+
+/** @internal */
+type DebugState = { type: keyof typeof stateTypes; name: string };
+
+// Serialize to memoize.
+const getStateFormatter = memoizeUnary((stateJson: string) => {
+  const stateStack = JSON.parse(stateJson) as unknown as DebugState[];
+  const firstState = stateStack.shift();
+  const left = stateTypes[firstState.type];
+  const right = [
+    firstState.name,
+    ...stateStack.map((state) => `${stateTypes[state.type]} ${state.name}`),
+  ].join(stateDelim);
+  return toBubblePrepender(left, right, toTheme("gray small"));
+});
+const getStatePrepender = (stateStack: DebugState[]) =>
+  getStateFormatter(JSON.stringify(stateStack));
+
+const overrideMethods = ["log", "error", "warn", "info", "debug"] as const;
+
+const identity = <T>(x: T) => x;
+
+const noop = (): (() => undefined) => undefined;
+
+/**
+ * A console, plus some methods to track event lifecycles.
+ * @internal
+ */
+export interface DebugLogger extends Console {
+  /**
+   * Stop all logging; methods do nothing
+   * @internal
+   */
+  detach(): void;
+  /**
+   * Add an event bubble to the log during handler.
+   */
+  pushState(state: DebugState): void;
+  /**
+   * Remove the bubble when event is done dispatching
+   */
+  popState(): void;
+}
+
+/**
+ * Returns a console whose methods autoformat with bubbles.
+ * @internal
+ */
+export function _customConsole(
+  theme: Theme,
+  type: string,
+  name: string
+): DebugLogger {
+  const prepender = toBubblePrepender(`X${type}`, name, toTheme(theme));
+  let statePrepender: LogDecorator = identity as LogDecorator;
+  const stateStack: DebugState[] = [];
+  const loggerProto: PropertyDescriptorMap = {
+    detach: {
+      writable: true,
+      configurable: true,
+      value(this: DebugLogger) {
+        overrideMethods.forEach((method) => {
+          this[method] = noop;
+        });
+      },
+    },
+    pushState: {
+      value(state: DebugState) {
+        stateStack.push(state);
+        statePrepender = getStatePrepender(stateStack);
+      },
+    },
+    popState: {
+      value() {
+        stateStack.pop();
+        statePrepender =
+          stateStack.length === 0
+            ? (identity as LogDecorator)
+            : getStatePrepender(stateStack);
+      },
+    },
+  };
+  const customConsole = Object.create(
+    console,
+    overrideMethods.reduce((out, level) => {
+      out[level] = {
+        writable: true,
+        configurable: true,
+        value(...args: unknown[]) {
+          console[level](...prepender(statePrepender(args)));
+        },
+      };
+      return out;
+    }, loggerProto)
+  ) as DebugLogger;
+  return customConsole;
+}
+
+/**
+ * @internal
+ */
+export const quietConsole = new Proxy(console, {
+  get() {
+    return noop;
+  },
+});

package/src/emitter.ts

@@ -0,0 +1,90 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import { Emits, Unsubscriber, NamedEvent } from "./types.js";
+
+/**
+ * Browser-native {@link https://developer.mozilla.org/en-US/docs/Web/API/EventTarget | EventTarget}
+ * whose {@link Emitter.addEventListener} method returns an anonymous function
+ * which unsubscribes the original handler.
+ *
+ * Also provides typed events via generics. You can create or extend this class
+ * to define custom emitters with known event names and signatures.
+ *
+ * @example
+ * ```ts
+ * import type { NamedEvent, Emitter } from '@adobe/uix-sdk'
+ *
+ * class FizzBuzzEmitter extends Emitter<
+ *   NamedEvent<"fizz", { fizzCount: number }> |
+ *   NamedEvent<"buzz", { buzzCount: number }> |
+ *   NamedEvent<"fizzbuzz">
+ * > {
+ * }
+ * ```
+ * The `FizzBuzzEmitter` class will now type check its events and event
+ * listeners, providing autosuggest in editors.
+ *
+ * @see [EventTarget - MDN](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget)
+ *
+ * @public
+ */
+export class Emitter<Events extends NamedEvent>
+  extends EventTarget
+  implements Emits<Events>
+{
+  /**
+   * An arbitrary string to uniquely identify this emitter and its events.
+   * @public
+   */
+  id: string;
+  constructor(id: string) {
+    super();
+    this.id = id;
+  }
+  /**
+   * Convenience method to construct and dispatch custom events.
+   *
+   * @param type - Name of one of the allowed events this can emit
+   * @param detail - Object to expose in the {@link https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/detail | CustomEvent#detail}
+   * property.
+   * @public
+   */
+  protected emit<Event extends Events>(
+    type: Event["type"],
+    detail: Event["detail"]
+  ): void {
+    const event = new CustomEvent<typeof detail>(type, { detail });
+    this.dispatchEvent(event);
+  }
+  /**
+   * Subscribe to an event and receive an unsubscribe callback.
+   * @see [EventTarget.addEventListener - MDN](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener)
+   *
+   * Identical to `EventTarget.addEventListener`, but returns an "unsubscriber"
+   * function which detaches the listener when invoked. Solves an ergonomic
+   * problem with native EventTargets where it's impossible to detach listeners
+   * without having a reference to the original handler.
+   *
+   * @typeParam E - Name of one of the allowed events this can emit
+   * @param type - Event type
+   * @param listener - Event handler
+   * @returns Call to unsubscribe listener.
+   */
+  addEventListener<
+    Type extends Events["type"],
+    Event extends Extract<Events, { type: Type }>
+  >(type: Type, listener: (ev: Event) => unknown): Unsubscriber {
+    super.addEventListener(type, listener);
+    return () => super.removeEventListener(type, listener);
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/**
+ * Core utilities, types and contracts for the Adobe UIX SDK.
+ * @packageDocumentation
+ */
+
+export * from "./debug-emitter";
+export * from "./debuglog";
+export * from "./emitter";
+export * from "./namespace-proxy";
+export * from "./timeout-promise";
+export * from "./types";

package/src/namespace-proxy.ts

@@ -0,0 +1,82 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { RemoteHostApis, RemoteMethodInvoker } from "./types.js";
+
+/**
+ * Build a fake object that turns "method calls" into RPC messages
+ * The resulting object will recursively make more fake proxies on demand until
+ * one of the looked-up properties is invoked as a function.
+ * Then it will call the passed `invoke` method with a {@link HostMethodAddress}
+ * that can send the method invocation as an RPC message to another realm.
+ *
+ * @example
+ * ```js
+ * const invoker = (methodAddress) => console.log(
+ *   address.path,
+ *   address.name,
+ *   address.args
+ * );
+ * const ns = makeNamespaceProxy(invoker);
+ *
+ * // looking up any property on the object will work
+ *
+ * ns.example.builds.method.call.message("foo", 1);
+ *
+ * // Console will log:
+ * ['example','builds','method','call']
+ * 'message'
+ * ["foo", 1]
+ *```
+ * @internal
+ *
+ * @param invoke - Callback that receives address
+ */
+export function makeNamespaceProxy<ProxiedApi extends object>(
+  invoke: RemoteMethodInvoker<unknown>,
+  path: string[] = []
+): RemoteHostApis<ProxiedApi> {
+  const handler: ProxyHandler<Record<string, any>> = {
+    get: (target, prop) => {
+      if (typeof prop === "string") {
+        if (!Reflect.has(target, prop)) {
+          const next = makeNamespaceProxy(invoke, path.concat(prop));
+          Reflect.set(target, prop, next);
+        }
+        return Reflect.get(target, prop) as unknown;
+      } else {
+        throw new Error(
+          `Cannot look up a symbol ${String(prop)} on a host connection proxy.`
+        );
+      }
+    },
+  };
+  const target = {} as unknown as RemoteHostApis<ProxiedApi>;
+  // Only trap the apply if there's at least two levels of namespace.
+  // uix.host() is not a function, and neither is uix.host.bareMethod().
+  if (path.length < 2) {
+    return new Proxy<RemoteHostApis<ProxiedApi>>(target, handler);
+  }
+  const invoker = (...args: unknown[]) =>
+    invoke({
+      path: path.slice(0, -1),
+      name: path[path.length - 1],
+      args,
+    });
+  return new Proxy<typeof invoker>(invoker, {
+    ...handler,
+    apply(target, _, args: unknown[]) {
+      return target(...args);
+    },
+  }) as unknown as typeof target;
+}

package/src/timeout-promise.ts

@@ -0,0 +1,36 @@
+/*
+Copyright 2022 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/**
+ * Add a timeout to a Promise. The returned Promise will resolve to the value of
+ * the original Promise, but if it doesn't resolve within the timeout interval,
+ * it will reject with a timeout error.
+ * @internal
+ *
+ * @param timeoutMs - Time to wait (ms) before rejecting
+ * @param promise - Original promise to set a timeout for
+ * @returns - Promise that rejects after X milliseconds have passed
+ */
+export function timeoutPromise<T>(timeoutMs: number, promise: Promise<T>) {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(
+      () => reject(new Error(`Timed out after ${timeoutMs}ms`)),
+      timeoutMs
+    );
+    promise
+      .then((result) => {
+        clearTimeout(timeout);
+        resolve(result);
+      })
+      .catch(reject);
+  });
+}