@shopify/ui-extensions 0.0.0-unstable-20230118190150

package/src/surfaces/checkout/style/style.test.ts

@@ -0,0 +1,131 @@
+import {Style} from './style';
+
+describe('Style', () => {
+  describe('default()', () => {
+    it('returns a conditional value with a default', () => {
+      const defaultValue = Style.default('default');
+
+      expect(defaultValue).toStrictEqual({
+        default: 'default',
+        conditionals: [],
+      });
+    });
+
+    it('returns a conditional value with a default and a condition when chained with when()', () => {
+      const defaultValue = Style.default('default');
+
+      expect(defaultValue.when({hover: true}, 'value')).toStrictEqual({
+        default: 'default',
+        conditionals: [{value: 'value', conditions: {hover: true}}],
+      });
+    });
+
+    it('returns a memoized value', () => {
+      expect(Style.default('default')).toBe(Style.default('default'));
+    });
+
+    it('returns a new value when passed value is different', () => {
+      expect(Style.default('default1')).not.toBe(Style.default('default2'));
+    });
+  });
+
+  describe('when()', () => {
+    it('returns a conditional value with no default', () => {
+      const conditionalValue = Style.when({hover: true}, 'value');
+
+      expect(conditionalValue).toStrictEqual({
+        conditionals: [{value: 'value', conditions: {hover: true}}],
+      });
+    });
+
+    it('returns a conditional value with a composed condition', () => {
+      const conditionalValue = Style.default('default').when(
+        {hover: true, viewportInlineSize: {min: 'small'}},
+        'value1',
+      );
+
+      expect(conditionalValue).toStrictEqual({
+        default: 'default',
+        conditionals: [
+          {
+            value: 'value1',
+            conditions: {hover: true, viewportInlineSize: {min: 'small'}},
+          },
+        ],
+      });
+    });
+
+    it('returns a memoized value', () => {
+      expect(Style.when({hover: true}, 'value')).toBe(
+        Style.when({hover: true}, 'value'),
+      );
+    });
+
+    it('returns a new value when passed value is different', () => {
+      expect(Style.when({hover: true}, 'value1')).not.toBe(
+        Style.when({hover: true}, 'value2'),
+      );
+    });
+  });
+
+  describe('when().when()', () => {
+    it('returns a conditional value with default and two conditions', () => {
+      const conditionalValue = Style.default('default')
+        .when({hover: true}, 'value1')
+        .when({viewportInlineSize: {min: 'small'}}, 'value2');
+
+      expect(conditionalValue).toStrictEqual({
+        default: 'default',
+        conditionals: [
+          {value: 'value1', conditions: {hover: true}},
+          {value: 'value2', conditions: {viewportInlineSize: {min: 'small'}}},
+        ],
+      });
+    });
+
+    it('returns a memoized value', () => {
+      expect(
+        Style.when({hover: true}, 'value 1')
+          .when({focus: true}, 'value 2')
+          .when({viewportInlineSize: {min: 'small'}}, 'value 3'),
+      ).toBe(
+        Style.when({hover: true}, 'value 1')
+          .when({focus: true}, 'value 2')
+          .when({viewportInlineSize: {min: 'small'}}, 'value 3'),
+      );
+    });
+
+    it('returns a memoized value after calling with a different value once', () => {
+      const firstValue = Style.when({hover: true}, 'value1').when(
+        {focus: true},
+        'value2',
+      );
+
+      Style.when({hover: true}, 'value1').when({focus: true}, 'value3');
+
+      const thirdValue = Style.when({hover: true}, 'value1').when(
+        {focus: true},
+        'value2',
+      );
+
+      expect(firstValue).toBe(thirdValue);
+    });
+  });
+
+  describe('prototype chain', () => {
+    it('returns a different when method on the prototype chain for each instance', () => {
+      const style1 = Style.when({hover: true}, 'value 1').when(
+        {viewportInlineSize: {min: 'small'}},
+        'value 2',
+      );
+      const style2 = Style.when({focus: true}, 'value 3').when(
+        {viewportInlineSize: {min: 'small'}},
+        'value 4',
+      );
+
+      expect(Object.getPrototypeOf(style1)).not.toBe(
+        Object.getPrototypeOf(style2),
+      );
+    });
+  });
+});

package/src/surfaces/checkout/style/style.ts

@@ -0,0 +1,161 @@
+import {memoize} from './memoize';
+import {Conditions, ConditionalStyle, BaseConditions} from './types';
+import {isEqual} from './isEqual';
+
+const MAX_CACHE_SIZE = 50;
+
+const MEMOIZE_OPTIONS = {
+  equalityCheck: isEqual,
+  maxSize: MAX_CACHE_SIZE,
+};
+
+type Chainable<TConditionalStyle> = TConditionalStyle extends ConditionalStyle<
+  infer T,
+  infer TAcceptedConditions
+>
+  ? TConditionalStyle & {
+      when: <
+        U,
+        AcceptedConditions extends BaseConditions = TAcceptedConditions,
+      >(
+        this: TConditionalStyle,
+        conditions: AcceptedConditions,
+        value: U,
+      ) => Chainable<
+        TConditionalStyle extends {default: T}
+          ? Required<ConditionalStyle<U, AcceptedConditions>>
+          : ConditionalStyle<U, AcceptedConditions>
+      >;
+    }
+  : never;
+
+type WhenContext<T, AcceptedConditions extends BaseConditions = Conditions> =
+  | typeof Style
+  | ConditionalStyle<T, AcceptedConditions>
+  | Required<ConditionalStyle<T, AcceptedConditions>>;
+
+type WhenReturnType<
+  T,
+  TContext extends WhenContext<any, AcceptedConditions>,
+  AcceptedConditions extends BaseConditions = Conditions,
+> = Chainable<
+  TContext extends typeof Style
+    ? ConditionalStyle<T, AcceptedConditions>
+    : TContext extends {default: infer U}
+    ? Required<ConditionalStyle<T | U, AcceptedConditions>>
+    : TContext extends {default?: infer U}
+    ? ConditionalStyle<T | U, AcceptedConditions>
+    : ConditionalStyle<T, AcceptedConditions>
+>;
+
+interface WhenFunction {
+  <
+    T,
+    TContext extends WhenContext<any, AcceptedConditions>,
+    AcceptedConditions extends BaseConditions = Conditions,
+  >(
+    this: TContext,
+    conditions: AcceptedConditions,
+    value: T,
+  ): WhenReturnType<T, TContext, AcceptedConditions>;
+}
+
+// eslint-disable-next-line func-style
+const when: WhenFunction = function when<
+  T,
+  TContext extends WhenContext<any, AcceptedConditions>,
+  AcceptedConditions extends BaseConditions = Conditions,
+>(this: TContext, conditions: AcceptedConditions, value: T) {
+  const config = isConditionalStyle<T, AcceptedConditions>(this)
+    ? {
+        default: this.default,
+        conditionals: [...this.conditionals, {conditions, value}],
+      }
+    : {
+        conditionals: [{conditions, value}],
+      };
+
+  return createChainableConditionalStyle<T, AcceptedConditions>(
+    config,
+  ) as WhenReturnType<T, TContext, AcceptedConditions>;
+};
+
+/**
+ * Style is a helper for authoring conditional values for prop styles.
+ * Write complex conditional styles based on one or more conditions (viewport
+ * sizes and interactive states) in a concise and expressive way.
+ */
+export const Style = {
+  /**
+   * Sets an optional default value to use when no other condition is met.
+   *
+   * @param defaultValue The default value
+   * @returns The chainable condition style
+   */
+  default: memoize(
+    <T, AcceptedConditions extends BaseConditions = Conditions>(
+      defaultValue: T,
+    ) =>
+      createChainableConditionalStyle<
+        T,
+        AcceptedConditions,
+        Required<ConditionalStyle<T, AcceptedConditions>>
+      >({
+        default: defaultValue,
+        conditionals: [],
+      }),
+    MEMOIZE_OPTIONS,
+  ),
+  /**
+   * Adjusts the style based on different conditions. All conditions, expressed
+   * as a literal object, must be met for the associated value to be applied.
+   *
+   * The `when` method can be chained together to build more complex styles.
+   *
+   * @param conditions The condition(s)
+   * @param value The conditional value that can be applied if the conditions are met
+   * @returns The chainable condition style
+   */
+  when: memoize(when, MEMOIZE_OPTIONS),
+} as const;
+
+function createChainableConditionalStyle<
+  T,
+  AcceptedConditions extends BaseConditions = Conditions,
+  TConditionalStyle extends ConditionalStyle<
+    T,
+    AcceptedConditions
+  > = ConditionalStyle<T, AcceptedConditions>,
+>(conditionalStyle: TConditionalStyle): Chainable<TConditionalStyle> {
+  const proto = {} as {
+    when: WhenFunction;
+  };
+
+  const returnConditionalStyle = Object.create(
+    proto,
+  ) as Chainable<TConditionalStyle>;
+
+  Object.assign(returnConditionalStyle, conditionalStyle);
+
+  proto.when = memoize(when.bind(returnConditionalStyle), MEMOIZE_OPTIONS);
+
+  return returnConditionalStyle;
+}
+
+export function isConditionalStyle<
+  T,
+  AcceptedConditions extends BaseConditions = Conditions,
+>(value?: any): value is ConditionalStyle<T, AcceptedConditions> {
+  return value !== null && typeof value === 'object' && 'conditionals' in value;
+}
+
+export function isConditionalStyleWithDefault<
+  T,
+  AcceptedConditions extends BaseConditions = Conditions,
+>(value?: any): value is Required<ConditionalStyle<T, AcceptedConditions>> {
+  return (
+    isConditionalStyle(value) &&
+    'default' in value &&
+    value.default !== undefined
+  );
+}

package/src/surfaces/checkout/style/types.ts

@@ -0,0 +1,67 @@
+type Resolution = 1 | 1.3 | 1.5 | 2 | 2.6 | 3 | 3.5 | 4;
+
+export interface InteractiveConditions {
+  hover: true;
+  focus: true;
+}
+
+export interface ResolutionCondition {
+  resolution: Resolution;
+}
+
+type ViewportInlineSize = 'small' | 'medium' | 'large';
+
+export interface ViewportSizeCondition {
+  viewportInlineSize: {min: ViewportInlineSize};
+}
+
+export type AtLeastOne<T, U = {[K in keyof T]: Pick<T, K>}> = Partial<T> &
+  U[keyof U];
+
+type DefaultConditions = InteractiveConditions & ViewportSizeCondition;
+
+export type Conditions = AtLeastOne<DefaultConditions>;
+
+export type BaseConditions = AtLeastOne<
+  DefaultConditions & ResolutionCondition
+>;
+
+export interface ConditionalValue<
+  T,
+  AcceptedConditions extends BaseConditions = Conditions,
+> {
+  /**
+   * The conditions that must be met for the value to be applied. At least one
+   * condition must be specified.
+   */
+  conditions: AcceptedConditions;
+  /**
+   * The value that will be applied if the conditions are met.
+   */
+  value: T;
+}
+
+export interface ConditionalStyle<
+  T,
+  AcceptedConditions extends BaseConditions = Conditions,
+> {
+  /**
+   * The default value applied when none of the conditional values
+   * specified in `conditionals` are met.
+   */
+  default?: T;
+  /**
+   * An array of conditional values.
+   */
+  conditionals: ConditionalValue<T, AcceptedConditions>[];
+}
+
+export type MaybeConditionalStyle<
+  T,
+  AcceptedConditions extends BaseConditions = Conditions,
+> = T | ConditionalStyle<T, AcceptedConditions>;
+
+export type MaybeResponsiveConditionalStyle<T> = MaybeConditionalStyle<
+  T,
+  ViewportSizeCondition
+>;

package/src/surfaces/checkout/style.ts

@@ -0,0 +1,16 @@
+export {
+  Style,
+  isConditionalStyle,
+  isConditionalStyleWithDefault,
+} from './style/style';
+export type {
+  AtLeastOne,
+  Conditions,
+  ConditionalStyle,
+  ConditionalValue,
+  InteractiveConditions,
+  MaybeConditionalStyle,
+  MaybeResponsiveConditionalStyle,
+  ResolutionCondition,
+  ViewportSizeCondition,
+} from './style/types';

package/src/surfaces/checkout.ts

@@ -0,0 +1,7 @@
+export * from './checkout/api';
+export * from './checkout/components';
+export * from './checkout/extension-points';
+export * from './checkout/extension';
+export * from './checkout/shared';
+export * from './checkout/style';
+export * from './checkout/globals';

package/src/utilities/registration.ts

@@ -0,0 +1,27 @@
+export interface ExtensionRegistrationFunction<ExtensionPoints> {
+  <Target extends keyof ExtensionPoints>(
+    target: Target,
+    implementation: ExtensionPoints[Target],
+  ): ExtensionPoints[Target];
+}
+
+/**
+ * This function takes an extension function that is expecting a `RemoteRoot` as its
+ * first argument, and returns a new function that accepts a `RemoteChannel` instead.
+ * This is a convenience that allows the raw UI extension API to only expose the simpler
+ * `RemoteChannel` type, while allowing the extension to use the more powerful `RemoteRoot`,
+ * provided by a version of `@remote-ui/core` that the extension controls.
+ */
+export function createExtensionRegistrationFunction<
+  ExtensionPoints,
+>(): ExtensionRegistrationFunction<ExtensionPoints> {
+  const extensionWrapper: ExtensionRegistrationFunction<ExtensionPoints> = (
+    target,
+    implementation,
+  ) => {
+    (globalThis as any).shopify?.extend(target, implementation);
+    return implementation;
+  };
+
+  return extensionWrapper;
+}