feat(pie-lottie-player): DSW-2365 implement lottie player

.changeset/itchy-lions-tickle.md

@@ -0,0 +1,5 @@
+---
+"pie-storybook": patch
+---
+
+[Added] - story and controls for pie-lottie-player

.changeset/shaggy-fishes-carry.md

@@ -0,0 +1,5 @@
+---
+"@justeattakeaway/pie-lottie-player": patch
+---
+
+[Added] - Component for playing Lottie animation files

.github/project-labeler.yml

@@ -85,6 +85,9 @@ pie-icon-button:
 pie-link:
 - 'packages/components/pie-link/**/*'
 
+pie-lottie-player:
+- 'packages/components/pie-lottie-player/**/*'
+
 pie-modal:
 - 'packages/components/pie-modal/**/*'
 

.github/workflows/ci.yml

@@ -36,6 +36,7 @@ env:
   PERCY_TOKEN_PIE_ICON_BUTTON: ${{ secrets.PERCY_TOKEN_PIE_ICON_BUTTON }}
   PERCY_TOKEN_PIE_ICONS_WEBC: ${{ secrets.PERCY_TOKEN_PIE_ICONS_WEBC }}
   PERCY_TOKEN_PIE_LINK: ${{ secrets.PERCY_TOKEN_PIE_LINK }}
+  PERCY_TOKEN_PIE_LOTTIE_PLAYER: ${{ secrets.PERCY_TOKEN_PIE_LOTTIE_PLAYER }}
   PERCY_TOKEN_PIE_MODAL: ${{ secrets.PERCY_TOKEN_PIE_MODAL }}
   PERCY_TOKEN_PIE_NOTIFICATION: ${{ secrets.PERCY_TOKEN_PIE_NOTIFICATION }}
   PERCY_TOKEN_PIE_RADIO: ${{ secrets.PERCY_TOKEN_PIE_RADIO }}

apps/pie-storybook/package.json

@@ -5,7 +5,7 @@
   "description": "Storybook for PIE Design System components",
   "scripts": {
     "dev": "storybook dev -p 6006",
-    "build": "storybook build --output-dir dist",
+    "build": "storybook build --output-dir dist && cp -R ./static ./dist",
     "lint:scripts": "run -T eslint .",
     "lint:scripts:fix": "run -T eslint . --fix",
     "generate:component-statuses": "npx generate-component-statuses"

apps/pie-storybook/stories/pie-lottie-player.stories.ts

@@ -0,0 +1,119 @@
+import { html } from 'lit';
+/* eslint-disable import/no-duplicates */
+import '@justeattakeaway/pie-lottie-player';
+import {
+    type LottiePlayerProps as LottiePlayerBaseProps, PieLottiePlayer, defaultProps, directions,
+} from '@justeattakeaway/pie-lottie-player';
+/* eslint-enable import/no-duplicates */
+
+import { type StoryMeta } from '../types';
+import { createStory } from '../utilities';
+
+type LottiePlayerProps = Omit<LottiePlayerBaseProps, 'play' | 'stop'>
+type LottiePlayerStoryMeta = StoryMeta<LottiePlayerProps>;
+
+const defaultArgs: LottiePlayerProps = { ...defaultProps };
+
+const animationSrcOptions: string[] = [
+    './static/animations/courier.json',
+    './static/animations/order-confirmed.json',
+    './static/animations/preparing.json',
+];
+
+const animationSrcLabels = animationSrcOptions.reduce<Record<string, string>>((acc, current) => {
+    const match = current.match(/.*\/(.*).json/);
+    acc[current] = match && match[1] ? match[1] : '';
+    return acc;
+}, {});
+
+const lottiePlayerStoryMeta: LottiePlayerStoryMeta = {
+    title: 'Lottie Player',
+    component: 'pie-lottie-player',
+    argTypes: {
+        animationSrc:  {
+            description: 'Lottie animation JSON file URL or relative path.\n animationSrc and animationData are mutually exclusive.',
+            control: {
+                type: 'select',
+                labels: animationSrcLabels,
+            },
+            options: [...animationSrcOptions, ''],
+            defaultValue: {
+                summary: defaultArgs.animationSrc,
+            },
+        },
+        loopDisabled: {
+            description: 'By the default animations loop, setting this prop as true will prevent such behaviour.',
+            control: 'boolean',
+            defaultValue: {
+                summary: defaultArgs.loopDisabled,
+            },
+        },
+        autoPlayDisabled: {
+            description: 'By default animations start playing as soons as its data is available, setting this prop as true will prevent such behaviour.',
+            control: 'boolean',
+            defaultValue: {
+                summary: defaultArgs.autoPlayDisabled,
+            },
+        },
+        speed: {
+            description: 'Determines the animation reproduction speed.\n1 is the regular speed, 2 is twice as fast.',
+            control: {
+                type: 'number',
+                step: 0.25,
+                min: 0.25,
+            },
+            defaultValue: {
+                summary: defaultArgs.speed,
+            },
+        },
+        direction: {
+            description: 'Sets the animation reproduction direction',
+            control: 'select',
+            options: directions,
+            defaultValue: {
+                summary: defaultArgs.direction,
+            },
+        },
+    },
+    args: defaultArgs,
+    parameters: {
+        design: {
+            type: 'figma',
+            url: '',
+        },
+    },
+};
+
+export default lottiePlayerStoryMeta;
+
+function handleStopAnimationClick () {
+    const player:PieLottiePlayer|null = document.querySelector('pie-lottie-player');
+    if (player) player.stop();
+}
+
+function handleStartAnimationClick () {
+    const player:PieLottiePlayer|null = document.querySelector('pie-lottie-player');
+    if (player) player.play();
+}
+
+const Template = ({
+    animationSrc,
+    loopDisabled,
+    autoPlayDisabled,
+    speed,
+    direction,
+}: LottiePlayerProps) => html`
+    <div style="display: flex; justify-content: center;">
+        <pie-button size="xsmall" @click=${handleStopAnimationClick}>Stop animation</pie-button>
+        <pie-button size="xsmall" @click=${handleStartAnimationClick}>Start animation</pie-button>
+    </div>
+    <pie-lottie-player
+        .animationSrc="${animationSrc === undefined ? animationSrcOptions[0] : animationSrc}"
+        ?loopDisabled="${loopDisabled}"
+        ?autoPlayDisabled="${autoPlayDisabled}"
+        .speed="${speed}"
+        .direction="${direction}"
+    ></pie-lottie-player>
+`;
+
+export const Default = createStory<LottiePlayerProps>(Template, defaultArgs)();

packages/components/pie-lottie-player/.eslintignore

@@ -0,0 +1,6 @@
+.turbo
+dist
+node_modules
+lit-browsers-report
+lit-visual-report
+test-results

packages/components/pie-lottie-player/README.md

@@ -0,0 +1,117 @@
+<p align="center">
+  <img align="center" src="../../../readme_image.png" height="200" alt="">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/@justeattakeaway/pie-lottie-player">
+    <img alt="GitHub Workflow Status" src="https://img.shields.io/npm/v/@justeattakeaway/pie-lottie-player.svg">
+  </a>
+</p>
+
+# Table of Contents
+
+1. [Introduction](#pie-lottie-player)
+2. [Installation](#installation)
+3. [Importing the component](#importing-the-component)
+4. [Peer Dependencies](#peer-dependencies)
+5. [Props](#props)
+5. [Acessibility](#acessibility)
+6. [Contributing](#contributing)
+
+## pie-lottie-player
+
+`pie-lottie-player` is a Web Component built using the Lit library.
+
+This component can be easily integrated into various frontend frameworks and customized through a set of properties.
+
+## Installation
+
+To install `pie-lottie-player` in your application, run the following on your command line:
+
+```bash
+# npm
+$ npm i @justeattakeaway/pie-lottie-player
+
+# yarn
+$ yarn add @justeattakeaway/pie-lottie-player
+```
+
+For full information on using PIE components as part of an application, check out the [Getting Started Guide](https://github.com/justeattakeaway/pie/wiki/Getting-started-with-PIE-Web-Components).
+
+### Importing the component
+
+#### JavaScript
+
+```js
+// Default – for Native JS Applications, Vue, Angular, Svelte, etc.
+import { PieLottiePlayer } from '@justeattakeaway/pie-lottie-player';
+
+// If you don't need to reference the imported object, you can simply
+// import the module which registers the component as a custom element.
+import '@justeattakeaway/pie-lottie-player';
+```
+
+#### React
+
+```js
+// React
+// For React, you will need to import our React-specific component build
+// which wraps the web component using ​@lit/react
+import { PieLottiePlayer } from '@justeattakeaway/pie-lottie-player/dist/react';
+```
+
+> [!NOTE]
+> When using the React version of the component, please make sure to also
+> include React as a [peer dependency](#peer-dependencies) in your project.
+
+#### Nuxt and SSR
+
+When adding this component to a Nuxt application in combination with SSR settings, it might happen to receive the error "500 customElements.get(...) is not a constructor" during the preview of the built application.
+
+That is likely due [a known issue](https://github.com/prashantpalikhe/nuxt-ssr-lit/issues/137) with the module that enables using Lit components in Nuxt with SSR, `nuxt-ssr-lit`.
+
+To solve the issue, update or add the `nitro.moduleSideEffects` array in `nuxt.config.ts`:
+
+```
+  nitro: {
+      moduleSideEffects: [
+          '@justeattakeaway/pie-lottie-player',
+      ],
+  },
+```
+
+## Peer Dependencies
+
+> [!IMPORTANT]
+> When using `pie-lottie-player`, you will also need to include a couple of dependencies to ensure the component renders as expected. See [the PIE Wiki](https://github.com/justeattakeaway/pie/wiki/Getting-started-with-PIE-Web-Components#expected-dependencies) for more information and how to include these in your application.
+
+## Props
+
+| Property         | Type      | Default | Description                                                                                                                  |
+| ---------------- | --------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| animationSrc | `String` | - | Lottie animation JSON file URL or relative path. animationSrc and animationData are mutually exclusive. |
+| animationData | `Object` | - | Object with Lottie animation data. animationSrc and animationData are mutually exclusive. |
+| loopDisabled | `Boolean` | false | By the default animations loop, setting this prop as true will prevent such behaviour. |
+| autoPlayDisabled | `Boolean` | false | By default animations start playing as soon as its data is available, setting this prop as true will prevent such behaviour. |
+| speed | `Number` | 1 | Determines the animation reproduction speed. 1 is the regular speed, 2 is twice as fast. |
+| direction | `String` | forward | Sets the animation reproduction direction. |
+
+In your markup or JSX, you can then use these to set the properties for the `pie-lottie-player` component:
+
+```html
+<!-- Native HTML -->
+<pie-lottie-player animationSrc="./animation-file.json"></pie-lottie-player>
+
+<!-- JSX -->
+<PieLottiePlayer animationSrc="./animation-file.json"></PieLottiePlayer>
+```
+
+## Acessibility
+
+Currently the component is always hidden from screen readers because animations should only be decorative and supplementary. Any important meaning and context should be presented alongside the animation as text.
+
+For the users with the "Reduce motion" setting enabled, the animation will be paused on the first frame.
+
+## Contributing
+
+Check out our [contributing guide](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide) for more information on [local development](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#local-development) and how to run specific [component tests](https://github.com/justeattakeaway/pie/wiki/Contributing-Guide#testing).

packages/components/pie-lottie-player/custom-elements-manifest.config.mjs

@@ -0,0 +1,15 @@
+import { moduleFileExtensionsPlugin } from 'cem-plugin-module-file-extensions';
+
+export default {
+    globs: [
+        './src/**/!(*.css).ts',
+    ],
+    exclude: [
+        '**/*.d.ts',
+        '**/*.d.js',
+        '**/react.ts',
+        '**/test/**',
+        '**/node_modules/**',
+    ],
+    plugins: [moduleFileExtensionsPlugin()],
+};

packages/components/pie-lottie-player/declaration.d.ts

@@ -0,0 +1,17 @@
+
+declare module '*.scss' {
+    const content: Record<string, string>;
+    export default content;
+}
+
+declare module '*.scss?inline' {
+    const content: Record<string, string>;
+    export default content;
+}
+
+declare module 'lottie-web/build/player/lottie_light_canvas.min.js' {
+    import { LottiePlayer } from 'lottie-web';
+
+    const lottie: LottiePlayer;
+    export default lottie;
+}

packages/components/pie-lottie-player/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@justeattakeaway/pie-lottie-player",
+  "description": "PIE Design System Lottie Player built using Web Components",
+  "version": "0.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "custom-elements.json",
+    "src",
+    "dist",
+    "**/*.d.ts"
+  ],
+  "pieMetadata": {
+    "componentStatus": "alpha"
+  },
+  "scripts": {
+    "build": "run -T vite build",
+    "build:react-wrapper": "npx build-react-wrapper",
+    "create:manifest": "yarn cem analyze --litelement",
+    "lint:scripts": "run -T eslint .",
+    "lint:scripts:fix": "yarn lint:scripts --fix",
+    "watch": "run -T vite build --watch",
+    "test": "echo \"Error: no test specified\" && exit 0",
+    "test:ci": "yarn test",
+    "test:browsers": "npx playwright test -c ./playwright-lit.config.ts",
+    "test:browsers:ci": "yarn test:browsers",
+    "test:visual": "run -T cross-env-shell PERCY_TOKEN=${PERCY_TOKEN_PIE_LOTTIE_PLAYER} percy exec --allowed-hostname cloudfront.net -- npx playwright test -c ./playwright-lit-visual.config.ts",
+    "test:visual:ci": "yarn test:visual",
+    "test:browsers-setup": "npx playwright-lit-setup"
+  },
+  "author": "Just Eat Takeaway.com - Design System Team",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@custom-elements-manifest/analyzer": "0.9.0",
+    "@justeattakeaway/pie-components-config": "0.18.0",
+    "@justeattakeaway/pie-css": "0.12.1",
+    "cem-plugin-module-file-extensions": "0.0.5"
+  },
+  "dependencies": {
+    "@justeattakeaway/pie-webc-core": "0.24.0",
+    "lottie-web": "5.12.2"
+  },
+  "volta": {
+    "extends": "../../../package.json"
+  },
+  "customElements": "custom-elements.json",
+  "sideEffects": [
+    "dist/*.js"
+  ]
+}

packages/components/pie-lottie-player/playwright-lit-visual.config.ts

@@ -0,0 +1,4 @@
+import { defineConfig } from '@sand4rt/experimental-ct-web';
+import { getPlaywrightVisualConfig } from '@justeattakeaway/pie-components-config';
+
+export default defineConfig(getPlaywrightVisualConfig());

packages/components/pie-lottie-player/playwright-lit.config.ts

@@ -0,0 +1,4 @@
+import { defineConfig } from '@sand4rt/experimental-ct-web';
+import { getPlaywrightConfig } from '@justeattakeaway/pie-components-config';
+
+export default defineConfig(getPlaywrightConfig());

packages/components/pie-lottie-player/src/defs-react.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+
+/**
+ * Use the React IntrinsicElements interface to find how to map standard HTML elements to existing React Interfaces
+ * Example: an HTML button maps to `React.ButtonHTMLAttributes<HTMLButtonElement>`
+ * https://github.com/DefinitelyTyped/DefinitelyTyped/blob/0bb210867d16170c4a08d9ce5d132817651a0f80/types/react/index.d.ts#L2829
+ */
+export type ReactBaseType = React.HTMLAttributes<HTMLDivElement>