hypnagaga/packages/graphics-components/docs/assets/Lottie-Bt8KBVq8.js

325 lines
19 KiB
JavaScript

import{j as e}from"./index-bIIEL2MP.js";import{useMDXComponents as r}from"./index-CO-0pc0F.js";import{M as i}from"./index-Z-6k0Xrj.js";import{L as s}from"./Lottie.stories-BvAQoFVB.js";import"./_commonjsHelpers-D6-XlEtG.js";import"./iframe-CzjIX-qr.js";import"./index-aQYXhgXp.js";import"./index-DrFu-skq.js";import"./props-b4vEeO_8.js";import"./runtime-C3rQLW--.js";import"./create-runtime-stories-7AWWVphH.js";import"./snippet-C5kbqVpq.js";import"./svelte-component-C8Ginrj8.js";import"./get-C3XmtPLd.js";import"./index-client-BAw8T8-V.js";import"./attributes-Cg6aLqN3.js";import"./style-DvJ3IcV1.js";import"./size-DMdj3-I9.js";import"./this-CrUBQEQ_.js";import"./tweened-4Ja_XIbT.js";import"./isEqualsSameValueZero-lFn2qCcO.js";import"./index-CCfEE_8A.js";import"./Block-D3Ui8rd-.js";import"./Markdown-DUxFwijc.js";import"./each-CVpBMMjG.js";import"./Headline-C-tkYFZ6.js";import"./Byline-BhU2Zjcl.js";import"./index-CX1x869l.js";import"./journalize-K6hK94UL.js";import"./Theme-BVfrVjCx.js";import"./flatten-CQmJgKju.js";import"./BodyText-CXnxLnBi.js";import"./ScrollerBase-DJMKplMV.js";import"./window-DXjFTZv5.js";const l=""+new URL("marker-DA6SPHlh.jpg",import.meta.url).href;function o(n){const t={a:"a",blockquote:"blockquote",code:"code",h1:"h1",h2:"h2",h3:"h3",li:"li",ol:"ol",p:"p",pre:"pre",strong:"strong",ul:"ul",...r(),...n.components};return e.jsxs(e.Fragment,{children:[e.jsx(i,{of:s}),`
`,e.jsx(t.h1,{id:"lottie",children:"Lottie"}),`
`,e.jsxs(t.p,{children:["The ",e.jsx(t.code,{children:"Lottie"})," component uses the ",e.jsx(t.a,{href:"https://developers.lottiefiles.com/docs/dotlottie-player/dotlottie-web/",rel:"nofollow",children:"dotLottie-web"})," library to render Lottie animations."]}),`
`,e.jsx(t.h2,{id:"how-to-prepare-lottie-files",children:"How to prepare Lottie files"}),`
`,e.jsxs(t.p,{children:[e.jsx(t.a,{href:"https://lottiefiles.com/",rel:"nofollow",children:"LottieFiles"})," is the official platform for creating and editing Lottie animations. The free version of LottieFiles has limited features, so ",e.jsx(t.a,{href:"https://exchange.adobe.com/apps/cc/12557/bodymovin",rel:"nofollow",children:"Bodymovin"})," remains a popular, free way to export Lottie animations as JSON files."]}),`
`,e.jsxs(t.p,{children:[e.jsx(t.a,{href:"https://dotlottie.io/",rel:"nofollow",children:"dotLottie"})," is another common format for Lottie files. This format bundles the Lottie JSON file and any associated assets, such as images and fonts, into a single compressed file with the extension ",e.jsx(t.code,{children:".lottie"}),"."]}),`
`,e.jsxs(t.p,{children:["This ",e.jsx(t.code,{children:"Lottie"})," component is flexible and supports both ",e.jsx(t.code,{children:"dotLottie"})," and JSON Lottie files. For best performance it is recommended that you convert your Lottie JSON file into a ",e.jsx(t.code,{children:".zip"})," file by following these steps:"]}),`
`,e.jsxs(t.ol,{children:[`
`,e.jsxs(t.li,{children:["Export your Lottie animation as a JSON file using ",e.jsx(t.a,{href:"https://exchange.adobe.com/apps/cc/12557/bodymovin",rel:"nofollow",children:"Bodymovin"})," or another Lottie exporter."]}),`
`,e.jsxs(t.li,{children:["Use the ",e.jsx(t.a,{href:"https://lottiefiles.com/tools/lottie-to-dotlottie",rel:"nofollow",children:"LottieFiles converter"})," to convert the JSON file into a ",e.jsx(t.code,{children:".lottie"})," file."]}),`
`,e.jsxs(t.li,{children:["Change the file extension to ",e.jsx(t.code,{children:".zip"})," from ",e.jsx(t.code,{children:".lottie"}),". This ensures full compatibility with the Reuters graphics publisher while maintaining the benefits of dotLottie format's compression and optimisation."]}),`
`]}),`
`,e.jsx(t.h2,{id:"when-not-to-use-lottie",children:"When not to use Lottie"}),`
`,e.jsx(t.p,{children:"Lottie animations are great for lightweight, scalable animations. However, they may not be suitable for all use cases. Consider the following before using Lottie:"}),`
`,e.jsxs(t.ul,{children:[`
`,e.jsxs(t.li,{children:[`
`,e.jsxs(t.p,{children:[e.jsx(t.strong,{children:"Huge raster images"}),": Lottie is best suited for simple to moderately complex animations. Animations with large raster images may not render well or could lead to performance issues. In such cases, consider using a ",e.jsx(t.a,{href:"?path=/docs/components-multimedia-video--docs",children:"Video"})," component or a ",e.jsx(t.a,{href:"?path=/docs/components-graphics-scrollervideo--docs",children:"ScrollerVideo"})," component instead."]}),`
`]}),`
`,e.jsxs(t.li,{children:[`
`,e.jsxs(t.p,{children:[e.jsx(t.strong,{children:"Complex effects"}),": Some advanced effects and features available in After Effects may not be fully supported in Lottie, which could lead to discrepancies between the original design and the rendered animation. Check the ",e.jsx(t.a,{href:"https://lottiefiles.com/supported-features",rel:"nofollow",children:"Lottie documentation"})," for a list of supported features."]}),`
`]}),`
`,e.jsxs(t.li,{children:[`
`,e.jsxs(t.p,{children:[e.jsx(t.strong,{children:"Text rendering"}),": Lottie renders text as vector shapes. If you need DOM text for accessibility or CSS manipulation, consider using HTML/CSS animations instead."]}),`
`]}),`
`,e.jsxs(t.li,{children:[`
`,e.jsxs(t.p,{children:[e.jsx(t.strong,{children:"SVG DOM manipulation"}),": Lottie renders animations on a canvas. If you need to manipulate individual elements of the animation using JavaScript or CSS, consider using SVG animations instead."]}),`
`]}),`
`]}),`
`,e.jsx(t.h2,{id:"basic-demo",children:"Basic demo"}),`
`,e.jsxs(t.p,{children:["To use the ",e.jsx(t.code,{children:"Lottie"})," component, import it and provide the Lottie animation source. The height of the container defaults to ",e.jsx(t.code,{children:"100lvh"}),", but you can adjust this to any valid CSS height value such as ",e.jsx(t.code,{children:"1200px"})," or ",e.jsx(t.code,{children:"200lvh"})," with the ",e.jsx(t.code,{children:"height"})," prop."]}),`
`,e.jsxs(t.p,{children:[e.jsxs(t.strong,{children:["Use ",e.jsx(t.code,{children:"lvh"})," or ",e.jsx(t.code,{children:"svh"})," units instead of ",e.jsx(t.code,{children:"vh"})]})," as ",e.jsx(t.a,{href:"https://www.w3.org/TR/css-values-4/#large-viewport-size",rel:"nofollow",children:"these units"})," are more reliable on mobile and other devices where elements such as the address bar appear and disappear and affect the height."]}),`
`,e.jsxs(t.p,{children:["The component also provides a ",e.jsx(t.code,{children:"width"})," prop to set the width of the Lottie container. While the ",e.jsx(t.code,{children:"width"})," prop defaults to ",e.jsx(t.code,{children:"fluid"}),", it allows any ",e.jsx(t.code,{children:"ContainerWidth"})," value such as ",e.jsx(t.code,{children:"narrower"}),", ",e.jsx(t.code,{children:"narrow"}),", ",e.jsx(t.code,{children:"normal"}),", ",e.jsx(t.code,{children:"wide"}),", ",e.jsx(t.code,{children:"wider"}),", ",e.jsx(t.code,{children:"widest"}),", ",e.jsx(t.code,{children:"fluid"}),", or a custom CSS width value like ",e.jsx(t.code,{children:"600px"})," or ",e.jsx(t.code,{children:"80vw"}),"."]}),`
`,e.jsxs(t.p,{children:["If importing the Lottie file directly into a Svelte component, make sure to append ",e.jsx(t.strong,{children:"?url"})," to the import statement (see example below). This ensures that the file is treated as a URL."]}),`
`,e.jsxs(t.blockquote,{children:[`
`,e.jsxs(t.p,{children:["💡TIP: Set ",e.jsx(t.code,{children:"showDebugInfo"})," prop to ",e.jsx(t.code,{children:"true"})," to display information about the component state."]}),`
`]}),`
`,e.jsx(t.p,{children:e.jsx(t.a,{href:"?path=/story/components-graphics-scrollerlottie--demo",children:"Demo"})}),`
`,e.jsx(t.pre,{children:e.jsx(t.code,{className:"language-svelte",children:`<script lang="ts">
import { Lottie } from '@reuters-graphics/graphics-components';
// Import Lottie file
import MyLottie from './lottie/my-lottie.zip?url'; // Append **?url** to the file path
<\/script>
<Lottie src={MyLottie} autoplay={true} showDebugInfo={true} />
`})}),`
`,e.jsx(t.h2,{id:"using-with-archieml",children:"Using with ArchieML"}),`
`,e.jsxs(t.p,{children:["If you are using ",e.jsx(t.code,{children:"Lottie"})," with ArchieML, store your Lottie zip file in the ",e.jsx(t.code,{children:"src/statics/lottie/"})," folder."]}),`
`,e.jsx(t.p,{children:"With the graphics kit, you'll likely get your text and prop values from an ArchieML doc..."}),`
`,e.jsx(t.pre,{children:e.jsx(t.code,{className:"language-yaml",children:`# ArchieML doc
[blocks]
type: lottie
# Lottie file stored in \`src/statics/lottie/\` folder
src: lottie/LottieFile.zip
autoplay: true
loop: true
showDebugInfo: true
[]
`})}),`
`,e.jsxs(t.p,{children:["... which you'll parse out of a ArchieML block object before passing to the ",e.jsx(t.code,{children:"Lottie"})," component."]}),`
`,e.jsx(t.pre,{children:e.jsx(t.code,{className:"language-svelte",children:`<script lang="ts">
import { Lottie } from '@reuters-graphics/graphics-components';
// Graphics kit only
import { assets } from '$app/paths'; // 👈 If using in the graphics kit...
import { truthy } from '$utils/propValidators'; // 👈 If using in the graphics kit...
<\/script>
{#each content.blocks as block}
<!-- Inside the content.blocks for loop... -->
{#if block.type == 'lottie'}
<Lottie
src={\`\${assets}/\${block.src}\`}
autoplay={truthy(block.autoplay)}
loop={truthy(block.loop)}
showDebugInfo={truthy(block.showDebugInfo)}
/>
{/if}
{/each}
`})}),`
`,e.jsx(t.h2,{id:"playing-a-segment",children:"Playing a segment"}),`
`,e.jsxs(t.p,{children:["The ",e.jsx(t.code,{children:"Lottie"})," component can play a specific segment of the Lottie animation using the ",e.jsx(t.code,{children:"segment"})," prop. The ",e.jsx(t.code,{children:"segment"})," prop expects an array of two numbers representing the start and end frames of the segment."]}),`
`,e.jsx(t.p,{children:e.jsx(t.a,{href:"?path=/story/components-graphics-scrollerlottie--segment",children:"Demo"})}),`
`,e.jsx(t.p,{children:"With the graphics kit, you'll likely get your text and prop values from an ArchieML doc..."}),`
`,e.jsx(t.pre,{children:e.jsx(t.code,{className:"language-yaml",children:`# ArchieML doc
[blocks]
type: lottie
showDebugInfo: true
loop: true
# Optionally, set playback speed
speed: 0.5
# Lottie file stored in \`src/statics/lottie/\` folder
src: lottie/LottieFile.zip
[.segment]
start: 0
end: 20
[]
[]
`})}),`
`,e.jsxs(t.p,{children:["... which you'll parse out of a ArchieML block object before passing to the ",e.jsx(t.code,{children:"Lottie"})," component."]}),`
`,e.jsx(t.pre,{children:e.jsx(t.code,{className:"language-svelte",children:`<script lang="ts">
import { Lottie } from '@reuters-graphics/graphics-components';
// Graphics kit only
import { assets } from '$app/paths'; // 👈 If using in the graphics kit...
import { truthy } from '$utils/propValidators'; // 👈 If using in the graphics kit...
<\/script>
{#each content.blocks as block}
<!-- Inside the content.blocks for loop... -->
{#if block.type == 'lottie'}
<Lottie
src={\`\${assets}/\${block.src}\`}
segment={[parseInt(block.segment.start), parseInt(block.segment.end)]}
showDebugInfo={truthy(block.showDebugInfo)}
loop={truthy(block.loop)}
speed={parseInt(block.speed)}
/>
{/if}
{/each}
`})}),`
`,e.jsx(t.h2,{id:"markers",children:"Markers"}),`
`,e.jsxs(t.p,{children:["The ",e.jsx(t.code,{children:"Lottie"})," component can also play a specific portion of the Lottie animation using markers set in ",e.jsx(t.a,{href:"https://helpx.adobe.com/in/after-effects/using/layer-markers-composition-markers.html",rel:"nofollow",children:"AfterEffects"}),"."]}),`
`,e.jsxs(t.p,{children:["The list of available markers, which can be passed into the ",e.jsx(t.code,{children:"marker"})," prop, can be found in the debug info box that appears when ",e.jsx(t.code,{children:"showDebugInfo"})," is set to ",e.jsx(t.code,{children:"true"}),"."]}),`
`,e.jsxs(t.p,{children:["When setting markers in AfterEffects, ensure that the ",e.jsx(t.strong,{children:"Comment"})," section of the Composition Marker contains only the name of your marker:"]}),`
`,e.jsx("img",{src:l,alt:"Composition Marker Dialog"}),`
`,e.jsx(t.p,{children:e.jsx(t.a,{href:"?path=/story/components-graphics-scrollerlottie--marker",children:"Demo"})}),`
`,e.jsx(t.pre,{children:e.jsx(t.code,{className:"language-svelte",children:`<script lang="ts">
import { Lottie } from '@reuters-graphics/graphics-components';
// Import Lottie file
import MyLottie from './lottie/my-lottie.zip?url'; // Append **?url** to the file path
<\/script>
<Lottie src={MyLottie} marker="myMarker" />
`})}),`
`,e.jsx(t.h2,{id:"switching-themes",children:"Switching themes"}),`
`,e.jsxs(t.p,{children:[e.jsx(t.a,{href:"https://lottiefiles.com/theming",rel:"nofollow",children:"Lottie Creator"})," allows you to define multiple colour themes for your animation. You can switch between these themes using the ",e.jsx(t.code,{children:"theme"})," prop."]}),`
`,e.jsxs(t.p,{children:["Available themes can be found in the debug info when the ",e.jsx(t.code,{children:"showDebugInfo"})," prop is set to ",e.jsx(t.code,{children:"true"}),"."]}),`
`,e.jsxs(t.p,{children:["You can set multiple themes and switch between them dynamically -- for example, based on the ",e.jsx(t.code,{children:"progress"})," of the animation."]}),`
`,e.jsx(t.p,{children:e.jsx(t.a,{href:"?path=/story/components-graphics-scrollerlottie--themes",children:"Demo"})}),`
`,e.jsx(t.pre,{children:e.jsx(t.code,{className:"language-svelte",children:`<script lang="ts">
import { Lottie } from '@reuters-graphics/graphics-components';
import MyLottie from './lottie/my-lottie.zip?url';
// Set a bindable \`progress\` variable to pass into \`<Lottie />\`
let progress = $state(0);
<\/script>
<Lottie
src={MyLottie}
bind:progress
themeId={progress < 0.33 ? 'Water'
: progress < 0.66 ? 'air'
: 'earth'}
autoplay
showDebugInfo
/>
`})}),`
`,e.jsxs(t.h2,{id:"using-with-scrollerbase",children:["Using with ",e.jsx(t.code,{children:"ScrollerBase"})]}),`
`,e.jsxs(t.p,{children:["The ",e.jsx(t.code,{children:"Lottie"})," component can be used with the ",e.jsx(t.code,{children:"ScrollerBase"})," component to create a more complex scrolling experience. ",e.jsx(t.code,{children:"ScrollerBase"})," provides a scrollable container sets the ",e.jsx(t.code,{children:"Lottie"})," component as a background."]}),`
`,e.jsx(t.pre,{children:e.jsx(t.code,{className:"language-svelte",children:`<script lang="ts">
import { Lottie, ScrollerBase } from '@reuters-graphics/graphics-components';
import MyLottie from './lottie/my-lottie.zip?url';
// Pass \`progress\` as \`videoPercentage\` to Lottie
let progress = $state(0);
<\/script>
<ScrollerBase bind:progress query="div.step-foreground-container">
{#snippet backgroundSnippet()}
<!-- Pass bindable prop \`progress\` as \`progress\` -->
<Lottie src={MyLottie} {progress} height="100lvh" showDebugInfo />
{/snippet}
{#snippet foregroundSnippet()}
<div class="step-foreground-container">
<h3 class="text-center">Step 1</h3>
</div>
<div class="step-foreground-container">
<h3 class="text-center">Step 2</h3>
</div>
<div class="step-foreground-container">
<h3 class="text-center">Step 3</h3>
</div>
{/snippet}
</ScrollerBase>
<style lang="scss">
.step-foreground-container {
height: 100lvh;
width: 50%;
margin: 0 auto;
h3 {
background-color: antiquewhite;
text-align: center;
}
}
</style>
`})}),`
`,e.jsx(t.h2,{id:"with-foregrounds",children:"With foregrounds"}),`
`,e.jsxs(t.p,{children:["The ",e.jsx(t.code,{children:"Lottie"})," component can also be used with the ",e.jsx(t.code,{children:"LottieForeground"})," component to display foreground elements at specific times in the animation."]}),`
`,e.jsxs(t.p,{children:[e.jsx(t.a,{href:"?path=/story/components-graphics-scrollerlottie--with-foregrounds",children:"Demo"}),"."]}),`
`,e.jsx(t.pre,{children:e.jsx(t.code,{className:"language-svelte",children:`<script lang="ts">
import { Lottie, ScrollerBase } from '@reuters-graphics/graphics-components';
import MyLottie from './lottie/my-lottie.zip?url';
<\/script>
<Lottie src={MyLottie} autoplay>
<!-- Foreground 1: Headline component as foreground -->
<LottieForeground
startFrame={0}
endFrame={50}
position="center center"
backgroundColour="rgba(0, 0, 0)"
>
<div class="headline-container">
<Theme base="dark">
<Headline
hed="Headline"
dek="This is an example of using a Svelte component as the foreground."
authors={['Jane Doe', 'John Doe']}
/>
</Theme>
</div>
</LottieForeground>
<!-- Foreground 2: Text only -->
<LottieForeground
startFrame={50}
endFrame={100}
text="Foreground caption between frames 50 and 100."
position="bottom center"
backgroundColour="rgba(0, 0, 0)"
width="wide"
/>
</Lottie>
`})}),`
`,e.jsx(t.h3,{id:"using-with-archieml-1",children:"Using with ArchieML"}),`
`,e.jsx(t.p,{children:"With the graphics kit, you'll likely get your text and prop values from an ArchieML doc..."}),`
`,e.jsx(t.pre,{children:e.jsx(t.code,{className:"language-yaml",children:`# ArchieML doc
[blocks]
type: lottie
# Lottie file stored in \`src/statics/lottie/\` folder
src: lottie/LottieFile.zip
# Array of foregrounds
[.foregrounds]
# Foreground 1: Headline component
startFrame: 0 # When in the animation to start showing the foreground
endFrame: 50 # When to stop showing the foreground
# Set foreground type
type: component
# Set props to pass into \`LottieForeground\`
{.foregroundProps}
componentName: Headline
hed: Headline
dek: Some deck text
[.authors]
* Jane Doe
* John Smith
[]
{}
# Foreground 2: Text only
startFrame: 50
endFrame: 100
# Set foreground type
type: text
# If the foreground type is \`text\`, set text prop here
{.foregroundProps}
text: Some text for the foreground
{}
[]
`})}),`
`,e.jsxs(t.p,{children:["... which you'll parse out of a ArchieML block object before passing to the ",e.jsx(t.code,{children:"Lottie"})," component."]}),`
`,e.jsx(t.pre,{children:e.jsx(t.code,{className:"language-svelte",children:`<script lang="ts">
import {
Lottie,
LottieForeground,
} from '@reuters-graphics/graphics-components';
import { assets } from '$app/paths';
// Make an object of components to use as foregrounds
const Components = $state({
Headline,
});
<\/script>
{#each content.blocks as block}
<!-- Inside the content.blocks for loop... -->
{#if block.type == 'lottie'}
<Lottie src={\`\${assets}/\${block.src}\`}>
{#each block.foregrounds as foreground}
{#if foreground.type == 'text'}
<LottieForeground
startFrame={parseInt(foreground.startFrame)}
endFrame={parseInt(foreground.endFrame)}
text={foreground.foregroundProps.text}
/>
{:else if foreground.type == 'component'}
{@const Component =
Components[foreground.foregroundProps.componentName]}
<LottieForeground
startFrame={parseInt(foreground.startFrame)}
endFrame={parseInt(foreground.endFrame)}
>
<Component {...foreground.foregroundProps} />
</LottieForeground>
{/if}
{/each}
</Lottie>
{/if}
{/each}
`})})]})}function U(n={}){const{wrapper:t}={...r(),...n.components};return t?e.jsx(t,{...n,children:e.jsx(o,{...n})}):o(n)}export{U as default};