@hkdigital/lib-core 0.3.1

package/dist/features/presenter/Presenter.svelte

@@ -0,0 +1,142 @@
+<script>
+  import { onMount } from 'svelte';
+
+  import { GridLayers } from '../../components/layout/index.js';
+
+  import { PresenterState } from './Presenter.state.svelte.js';
+  import { cssBefore, cssDuring, waitForRender } from './util.js';
+
+  /**
+   * @typedef {import("./typedef.js").Slide} Slide
+   */
+
+  /**
+   * @typedef {import("./typedef.js").Layer} Layer
+   */
+
+  /**
+   * @type {{
+   *   classes?: string,
+   *   slides?: import("./typedef.js").Slide[],
+   *   presenterRef?: import('./Presenter.state.svelte.js').PresenterRef,
+   *   layoutSnippet: import('svelte').Snippet<[Slide|null, Layer]>,
+   *   loadingSnippet?: import('svelte').Snippet,
+   * }}
+   */
+  let {
+    // > Style
+    classes,
+
+    // > Functional
+    slides,
+    presenterRef = $bindable(),
+
+    // Snippets
+    layoutSnippet,
+    loadingSnippet
+  } = $props();
+
+  const presenter = new PresenterState();
+
+  onMount(() => {
+    // Configure presenter with slides if provided
+    presenter.configure({ slides });
+    presenterRef = presenter.getPresenterRef();
+  });
+
+  // > State
+
+  let classesA = $state('');
+  let classesB = $state('');
+
+  let stylesA = $state('');
+  let stylesB = $state('');
+
+  //> Apply stage classes and styles
+
+  $effect(() => {
+    // > layerA
+
+    const { stageBeforeIn, stageIn, stageBeforeOut, stageOut, transitions } =
+      presenter.layerA;
+
+    if (transitions?.length) {
+      // console.debug('layerA:transitions', transitions, {
+      //   stageBeforeIn,
+      //   stageIn,
+      //   stageBeforeOut,
+      //   stageOut
+      // });
+
+      if (stageBeforeIn || stageBeforeOut) {
+        ({ style: stylesA, classes: classesA } = cssBefore(transitions));
+      } else if (stageIn || stageOut) {
+        waitForRender(() => {
+          ({ style: stylesA, classes: classesA } = cssDuring(transitions));
+        });
+      }
+    } else {
+      stylesA = '';
+      classesA = '';
+    }
+  });
+
+  $effect(() => {
+    // > layerB
+
+    const { stageBeforeIn, stageIn, stageBeforeOut, stageOut, transitions } =
+      presenter.layerB;
+
+    if (transitions?.length) {
+      // console.debug('layerB:transitions', transitions, {
+      //   stageBeforeIn,
+      //   stageIn,
+      //   stageBeforeOut,
+      //   stageOut
+      // });
+
+      if (stageBeforeIn || stageBeforeOut) {
+        ({ style: stylesB, classes: classesB } = cssBefore(transitions));
+      } else if (stageIn || stageOut) {
+        waitForRender(() => {
+          ({ style: stylesB, classes: classesB } = cssDuring(transitions));
+        });
+      }
+    } else {
+      stylesB = '';
+      classesB = '';
+    }
+  });
+</script>
+
+<GridLayers data-feature="presenter" {classes}>
+  <div
+    data-layer="layer1"
+    style:z-index={presenter.layerA.z}
+    style:visibility={presenter.layerA.visible ? 'visible' : 'hidden'}
+    inert={presenter.busy}
+    class="justify-self-stretch self-stretch overflow-hidden"
+  >
+    <div class="{classesA} h-full w-full grid" style={stylesA}>
+      {@render layoutSnippet(presenter.slideA, presenter.layerA)}
+    </div>
+  </div>
+
+  <div
+    data-layer="layer2"
+    style:z-index={presenter.layerB.z}
+    style:visibility={presenter.layerB.visible ? 'visible' : 'hidden'}
+    inert={presenter.busy}
+    class="justify-self-stretch self-stretch overflow-hidden"
+  >
+    <div class="{classesB} h-full w-full grid" style={stylesB}>
+      {@render layoutSnippet(presenter.slideB, presenter.layerB)}
+    </div>
+  </div>
+
+  {#if loadingSnippet && presenter.loadingSpinner}
+    <div class="justify-self-stretch self-stretch overflow-hidden grid z-[20]">
+      {@render loadingSnippet()}
+    </div>
+  {/if}
+</GridLayers>

package/dist/features/presenter/Presenter.svelte.d.ts

@@ -0,0 +1,18 @@
+export default Presenter;
+type Presenter = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<{
+        classes?: string;
+        slides?: Slide[];
+        presenterRef?: PresenterRef;
+        layoutSnippet: Snippet<[Slide, Layer]>;
+        loadingSnippet?: Snippet<[]>;
+    }>): void;
+};
+declare const Presenter: import("svelte").Component<{
+    classes?: string;
+    slides?: import("./typedef.js").Slide[];
+    presenterRef?: import("./Presenter.state.svelte.js").PresenterRef;
+    layoutSnippet: import("svelte").Snippet<[import("./typedef.js").Slide | null, import("./typedef.js").Layer]>;
+    loadingSnippet?: import("svelte").Snippet;
+}, {}, "presenterRef">;

package/dist/features/presenter/constants.d.ts

@@ -0,0 +1,5 @@
+export const TRANSITION_CSS: "css";
+export const FADE_IN: "fade-in";
+export const FADE_OUT: "fade-out";
+export const STAGE_BEFORE: "stage-before";
+export const STAGE_SHOW: "stage-show";

package/dist/features/presenter/constants.js

@@ -0,0 +1,7 @@
+export const TRANSITION_CSS = 'css';
+
+export const FADE_IN = 'fade-in';
+export const FADE_OUT = 'fade-out';
+
+export const STAGE_BEFORE = 'stage-before';
+export const STAGE_SHOW = 'stage-show';

package/dist/features/presenter/index.d.ts

@@ -0,0 +1,6 @@
+export { default as Presenter } from "./Presenter.svelte";
+export { default as ImageSlide } from "./ImageSlide.svelte";
+export { PresenterState } from "./Presenter.state.svelte.js";
+export * from "./typedef.js";
+export * from "./constants.js";
+export * from "./util.js";

package/dist/features/presenter/index.js

@@ -0,0 +1,10 @@
+export { default as Presenter } from './Presenter.svelte';
+export { default as ImageSlide } from './ImageSlide.svelte';
+
+export { PresenterState } from './Presenter.state.svelte.js';
+
+export * from './typedef.js';
+export * from './constants.js';
+
+// @ts-ignore
+export * from './util.js';

package/dist/features/presenter/typedef.d.ts

@@ -0,0 +1,92 @@
+declare const _default: {};
+export default _default;
+export type CssTransition = {
+    type: ("css");
+    property: string;
+    from: string;
+    to: string;
+    delay?: number;
+    duration?: number;
+    timing?: string;
+};
+export type FadeInTransition = {
+    type: ("fade-in");
+    from?: string;
+    to?: string;
+    delay?: number;
+    duration?: number;
+    timing?: string;
+};
+export type FadeOutTransition = {
+    type: ("fade-out");
+    from?: string;
+    to?: string;
+    delay?: number;
+    duration?: number;
+    timing?: string;
+};
+export type LoadController = {
+    /**
+     * - Function to call when loading is complete
+     */
+    loaded: () => void;
+    /**
+     * - Function to return to the previous slide
+     */
+    cancel: () => void;
+};
+export type ListenerParams = {
+    stage: string;
+    slideName: string;
+};
+export type ListenerCallback = (params: ListenerParams) => () => void;
+export type UnregisterFn = () => void;
+export type PresenterRef = {
+    /**
+     * - Navigate to a slide by name
+     */
+    gotoSlide: (name: string) => void;
+    /**
+     * - Get the current slide name
+     */
+    getCurrentSlideName: () => string;
+    /**
+     *   Register listener that is called when a slide enters state 'before'
+     */
+    onBefore: (callback: ListenerCallback) => UnregisterFn;
+    /**
+     *   Register listener that is called when a slide enters state 'show'
+     */
+    onShow: (callback: ListenerCallback) => UnregisterFn;
+};
+export type Transition = CssTransition | FadeInTransition | FadeOutTransition;
+export type SlideData = {
+    [attrs: string]: any;
+};
+export type SlideLayerLayout = {
+    [attrs: string]: any;
+};
+export type SlideLayer = {
+    data?: SlideData;
+    layout?: SlideLayerLayout;
+};
+export type Slide = {
+    name: string;
+    data?: SlideData;
+    layers?: SlideLayer[];
+    intro?: Transition[];
+    outro?: Transition[];
+    duration?: number;
+};
+export type Layer = {
+    z: number;
+    visible: boolean;
+    stageIdle?: boolean;
+    stageBeforeIn?: boolean;
+    stageIn?: boolean;
+    stageShow?: boolean;
+    stageBeforeOut?: boolean;
+    stageOut?: boolean;
+    stageAfter?: boolean;
+    transitions?: Transition[];
+};

package/dist/features/presenter/typedef.js

@@ -0,0 +1,106 @@
+/**
+ * @typedef {{
+ *     type: (import('./constants').TRANSITION_CSS),
+ *     property: string,
+ *     from: string,
+ *     to: string,
+ *     delay?: number
+ *     duration?: number
+ *     timing?: string
+ * }} CssTransition
+ */
+
+/**
+ * @typedef {{
+ *     type: (import('./constants').FADE_IN),
+ *     from?: string,
+ *     to?: string,
+ *     delay?: number
+ *     duration?: number
+ *     timing?: string
+ * }} FadeInTransition
+ */
+
+/**
+ * @typedef {{
+ *     type: (import('./constants').FADE_OUT),
+ *     from?: string,
+ *     to?: string,
+ *     delay?: number
+ *     duration?: number
+ *     timing?: string
+ * }} FadeOutTransition
+ */
+
+/**
+ * @typedef {Object} LoadController
+ * @property {() => void} loaded - Function to call when loading is complete
+ * @property {() => void} cancel - Function to return to the previous slide
+ */
+
+/**
+ * @typedef {{
+ *   stage: string,
+ *   slideName: string
+ * }} ListenerParams
+ */
+
+/**
+ * @typedef {( params: ListenerParams) => () => void } ListenerCallback
+ */
+
+/**
+ * @typedef {() => void } UnregisterFn
+ */
+
+/**
+ * @typedef {Object} PresenterRef
+ * @property {(name: string) => void} gotoSlide - Navigate to a slide by name
+ * @property {() => string} getCurrentSlideName - Get the current slide name
+ * @property {( callback: ListenerCallback ) => UnregisterFn} onBefore
+ *   Register listener that is called when a slide enters state 'before'
+ * @property {( callback: ListenerCallback ) => UnregisterFn} onShow
+ *   Register listener that is called when a slide enters state 'show'
+ */
+
+/**
+ * @typedef {CssTransition|FadeInTransition|FadeOutTransition} Transition
+ */
+
+/**
+ * @typedef {{[attrs: string]: *}} SlideData
+ */
+
+/**
+ * @typedef {{[attrs: string]: *}} SlideLayerLayout
+ */
+
+/**
+ * @typedef {{data?:SlideData, layout?:SlideLayerLayout}} SlideLayer
+ */
+
+/**
+ * @typedef {object} Slide
+ * @property {string} name
+ * @property {SlideData} [data]
+ * @property {SlideLayer[]} [layers]
+ * @property {Transition[]} [intro]
+ * @property {Transition[]} [outro]
+ * @property {number} [duration]
+ */
+
+/**
+ * @typedef {object} Layer
+ * @property {number} z
+ * @property {boolean} visible
+ * @property {boolean} [stageIdle]
+ * @property {boolean} [stageBeforeIn]
+ * @property {boolean} [stageIn]
+ * @property {boolean} [stageShow]
+ * @property {boolean} [stageBeforeOut]
+ * @property {boolean} [stageOut]
+ * @property {boolean} [stageAfter]
+ * @property {Transition[]} [transitions]
+ */
+
+export default {};

package/dist/features/presenter/util.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @typedef {import("./typedef").Transition} Transition
+ */
+/**
+ * Ensures DOM is updated by Svelte and then painted by the browser
+ * before executing the callback function.
+ *
+ * @param {Function} callback - Function to execute after DOM update and paint
+ * @returns {Promise<void>} - Promise that resolves after the callback is executed
+ */
+export function waitForRender(callback: Function): Promise<void>;
+/** === Generate CSS for lists of transitions */
+/**
+ * Generates style and class names to be used before the transitions
+ * become active
+ *
+ * @param {Transition[]} transitions
+ *
+ * @returns {{style: string, classes: string}}
+ */
+export function cssBefore(transitions: Transition[]): {
+    style: string;
+    classes: string;
+};
+/**
+ * Generates style and class names to be used when the transitions are active
+ *
+ * @param {Transition[]} transitions
+ *
+ * @returns {{style: string, classes: string}}
+ */
+export function cssDuring(transitions: Transition[]): {
+    style: string;
+    classes: string;
+};
+/** === Generate CSS for single transitions */
+/**
+ * Generates style and class names for specified transition for
+ * the stage 'stageBeforeIn'
+ *
+ * @param {Transition} transition
+ *
+ * @returns {{propertyStyle: string, transitionStyle: string, classes: string}}
+ */
+export function transitionCssBefore(transition: Transition): {
+    propertyStyle: string;
+    transitionStyle: string;
+    classes: string;
+};
+/**
+ * Generates style and class names for specified transition for
+ * the stage 'stageIn'
+ *
+ * @param {Transition} transition
+ *
+ * @returns {{propertyStyle: string, transitionStyle: string, classes: string}}
+ */
+export function transitionCssDuring(transition: Transition): {
+    propertyStyle: string;
+    transitionStyle: string;
+    classes: string;
+};
+export type Transition = import("./typedef").Transition;

package/dist/features/presenter/util.js

@@ -0,0 +1,210 @@
+import { tick } from 'svelte';
+
+import * as expect from '../../util/expect/index.js';
+
+import { pushNotEmpty } from '../../util/array/index.js';
+
+import { TRANSITION_CSS, FADE_IN, FADE_OUT } from './constants.js';
+
+/**
+ * @typedef {import("./typedef").Transition} Transition
+ */
+
+/**
+ * Ensures DOM is updated by Svelte and then painted by the browser
+ * before executing the callback function.
+ *
+ * @param {Function} callback - Function to execute after DOM update and paint
+ * @returns {Promise<void>} - Promise that resolves after the callback is executed
+ */
+export function waitForRender(callback) {
+  return tick().then(() => {
+    return new Promise((resolve) => {
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          setTimeout(() => {
+            callback();
+            resolve();
+          }, 20);
+        });
+      });
+    });
+  });
+}
+
+/** === Generate CSS for lists of transitions */
+
+/**
+ * Generates style and class names to be used before the transitions
+ * become active
+ *
+ * @param {Transition[]} transitions
+ *
+ * @returns {{style: string, classes: string}}
+ */
+export function cssBefore(transitions) {
+  expect.objectArray(transitions);
+
+  /** @type {string[]} */ let propertyStyleArr = [];
+  /** @type {string[]} */ let transitionStyleArr = [];
+  /** @type {string[]} */ let classesArr = [];
+
+  for (const transition of transitions) {
+    const { propertyStyle, transitionStyle, classes } =
+      transitionCssBefore(transition);
+
+    pushNotEmpty(propertyStyleArr, propertyStyle);
+    pushNotEmpty(transitionStyleArr, transitionStyle);
+    pushNotEmpty(classesArr, classes);
+  }
+
+  let style = propertyStyleArr.join(';');
+
+  if (transitionStyleArr.length) {
+    style += `;transition: ${transitionStyleArr.join(',')}`;
+  }
+
+  // console.log('cssBefore', transitions, style);
+
+  return { style, classes: classesArr.join() };
+}
+
+/**
+ * Generates style and class names to be used when the transitions are active
+ *
+ * @param {Transition[]} transitions
+ *
+ * @returns {{style: string, classes: string}}
+ */
+export function cssDuring(transitions) {
+  expect.objectArray(transitions);
+
+  /** @type {string[]} */ let propertyStyleArr = [];
+  /** @type {string[]} */ let transitionStyleArr = [];
+  /** @type {string[]} */ let classesArr = [];
+
+  for (const transition of transitions) {
+    const { propertyStyle, transitionStyle, classes } =
+      transitionCssDuring(transition);
+
+    pushNotEmpty(propertyStyleArr, propertyStyle);
+    pushNotEmpty(transitionStyleArr, transitionStyle);
+    pushNotEmpty(classesArr, classes);
+  } // end for
+
+  let style = propertyStyleArr.join(';');
+
+  if (transitionStyleArr.length) {
+    style += `;transition: ${transitionStyleArr.join(',')}`;
+  }
+
+  return { style, classes: classesArr.join() };
+}
+
+/** === Generate CSS for single transitions */
+
+/**
+ * Generates style and class names for specified transition for
+ * the stage 'stageBeforeIn'
+ *
+ * @param {Transition} transition
+ *
+ * @returns {{propertyStyle: string, transitionStyle: string, classes: string}}
+ */
+export function transitionCssBefore(transition) {
+  expect.objectNoArray(transition);
+
+  let {
+    type,
+    // @ts-ignore
+    property,
+    from
+  } = transition;
+
+  let propertyStyle = '';
+  let transitionStyle = '';
+  let classes = '';
+
+  switch (type) {
+    case FADE_IN:
+      type = TRANSITION_CSS;
+      property = 'opacity';
+      from = from ?? '0';
+      break;
+
+    case FADE_OUT:
+      type = TRANSITION_CSS;
+      property = 'opacity';
+      from = from ?? '1';
+      break;
+  }
+
+  if (!type || TRANSITION_CSS === type) {
+    expect.notEmptyString(property);
+    expect.string(from);
+
+    propertyStyle = `${property}: ${from}`;
+  } else {
+    throw new Error(`Unknown transition type [${type}]`);
+  }
+
+  // console.log('transitionCssBefore', { propertyStyle, transitionStyle });
+
+  return { propertyStyle, transitionStyle, classes };
+}
+
+/**
+ * Generates style and class names for specified transition for
+ * the stage 'stageIn'
+ *
+ * @param {Transition} transition
+ *
+ * @returns {{propertyStyle: string, transitionStyle: string, classes: string}}
+ */
+export function transitionCssDuring(transition) {
+  expect.objectNoArray(transition);
+
+  let {
+    type,
+    // @ts-ignore
+    property,
+    to,
+    delay = 0,
+    duration = 1000,
+    timing = 'ease'
+  } = transition;
+
+  let propertyStyle;
+  let transitionStyle;
+  let classes = '';
+
+  switch (type) {
+    case FADE_IN:
+      type = TRANSITION_CSS;
+      property = 'opacity';
+      to = to ?? '1';
+      break;
+
+    case FADE_OUT:
+      type = TRANSITION_CSS;
+      property = 'opacity';
+      to = to ?? '0';
+      break;
+  }
+
+  if (!type || TRANSITION_CSS === type) {
+    expect.notEmptyString(property);
+    expect.string(to);
+
+    propertyStyle = `${property}: ${to}`;
+
+    /* property name | duration | easing function | delay */
+    transitionStyle = `${property} ${duration}ms ${timing} ${delay}ms`;
+  } else {
+    throw new Error(`Unknown transition type [${type}]`);
+  }
+
+  // console.log('transitionCssDuring', { propertyStyle, transitionStyle });
+
+  return { propertyStyle, transitionStyle, classes };
+}