svelte-screen-stack

Svelte Screen Stack

A library which helps you handle create easy and smooth transitions during navigation between screens and provides utils to manage screen stack management.

Installation

In order to install run the following command

npm i svelte-screen-stack

Usage

In order to start using Svelte Screen Stack, you need to following:

• Creating a ScreenStack

• Importing
• Props
• Controlling

✨ Jump to Example ✨

Creating a ScreenStack

Importing

import { ScreenStack } from 'svelte-screen-stack';

Props

The ScreenStack takes following parameters:

Prop Name	Type	Description	Default Value
initialScreen	string	The name of the screen to display at the beginning	(required)
animation	ScreenAnimation	The animation to use when transitioning between screens	'slide'

The ScreenAnimation type can be either a string preset ('slide') or a custom animation object with the following structure:

type ScreenAnimation =
  | 'slide'
  | {
      entry: Array<{
        property: string; // CSS property to animate (e.g., 'transformX', 'scale', 'opacity')
        duration: number; // Duration of the animation in milliseconds
        interpolator: Function; // Easing function for the animation
        from: number; // Starting value
        to: number; // Ending value
      }>;
      exit: Array<{
        property: string;
        duration: number;
        interpolator: Function;
        from: number;
        to: number;
      }>;
    };

You can use the built-in cubicBezier utility function to create custom interpolators:

import { cubicBezier } from 'svelte-screen-stack';

const customAnimation = {
  entry: [
    {
      property: 'transformX',
      duration: 300,
      interpolator: cubicBezier(0.52, 0.85, 0.54, 0.91),
      from: window.screen.width,
      to: 0
    }
  ],
  exit: [
    {
      property: 'transformX',
      duration: 300,
      interpolator: cubicBezier(1, 0.06, 0.96, 0.32),
      from: 0,
      to: window.screen.width
    }
  ]
};

Invocation

To use the ScreenStack component in your Svelte application:

• Import the necessary components:

import {(ScreenStack, Screen, ScreenStackController, cubicBezier)} from 'svelte-screen-stack';

• Create a reference to the ScreenStack and define animation if needed:

<script>
  import { onMount, type SvelteComponent } from 'svelte';

  let screenStack: SvelteComponent;

  // Optional: Define custom animation
  let animation = {
    entry: [
      {
        property: 'transformX',
        duration: 300,
        interpolator: cubicBezier(0.52, 0.85, 0.54, 0.91),
        from: window.screen.width,
        to: 0
      }
    ],
    exit: [
      {
        property: 'transformX',
        duration: 300,
        interpolator: cubicBezier(1, 0.06, 0.96, 0.32),
        from: 0,
        to: window.screen.height
      }
    ]
  };
</script>

• Create the ScreenStack in your markup with Screen components:

<ScreenStack initialScreen="1" bind:this={screenStack} {animation}>
  <Screen name="1">
    <div class="screen-content">
      <h1>Screen One</h1>
    </div>
  </Screen>

  <Screen name="2">
    <div class="screen-content">
      <h1>Screen Two</h1>
    </div>
  </Screen>

  <Screen name="3">
    <div class="screen-content">
      <h1>Screen Three</h1>
    </div>
  </Screen>
</ScreenStack>

• Initialize the ScreenStackController to control navigation:

<script>
  let screenController: ScreenStackController;

  onMount(() => {
    screenController = new ScreenStackController(screenStack, true);
  });
</script>

Controlling ScreenStack Navigation

The ScreenStackController class provides methods to control screen navigation:

Method	Parameters	Description
changeScreen	screenName: string	Navigates to the specified screen
goBack	None	Navigates back to the previous screen in the stack

Example

Here's a complete functional example of implementing a screen stack with custom animations:

<script lang="ts">
  import {
    ScreenStackController,
    ScreenStack,
    type ScreenAnimation,
    Screen,
    cubicBezier
  } from 'svelte-screen-stack';
  import { onMount, type SvelteComponent } from 'svelte';

  // Create references for screen stack and controller
  let screenController: ScreenStackController;
  let screenStack: SvelteComponent;

  // Define custom animations
  let animation: ScreenAnimation = {
    entry: [
      {
        property: 'transformX',
        duration: 300,
        interpolator: cubicBezier(0.52, 0.85, 0.54, 0.91),
        from: window.screen.width,
        to: 0
      },
      {
        property: 'scale',
        duration: 300,
        interpolator: cubicBezier(0.52, 0.85, 0.54, 0.91),
        from: 0.8,
        to: 1
      }
    ],
    exit: [
      {
        property: 'transformX',
        duration: 300,
        interpolator: cubicBezier(1, 0.06, 0.96, 0.32),
        from: 0,
        to: window.screen.width
      },
      {
        property: 'scale',
        duration: 300,
        interpolator: cubicBezier(0.52, 0.85, 0.54, 0.91),
        from: 1,
        to: 0.8
      }
    ]
  };

  onMount(() => {
    // Initialize the screen controller
    screenController = new ScreenStackController(screenStack, true);
  });
</script>

<!-- Screen stack container -->
<div class="screen-container">
  <ScreenStack initialScreen="dashboard" bind:this={screenStack} {animation}>
    <!-- Dashboard Screen -->
    <Screen name="dashboard">
      <div class="screen-content dashboard">
        <h1>Dashboard</h1>
        <p>Welcome to your application dashboard!</p>
        <button on:click={() => screenController.changeScreen('profile')}> View Profile </button>
        <button on:click={() => screenController.changeScreen('settings')}> Settings </button>
      </div>
    </Screen>

    <!-- Profile Screen -->
    <Screen name="profile">
      <div class="screen-content profile">
        <h1>User Profile</h1>
        <div class="profile-info">
          <div class="avatar">👤</div>
          <h2>John Doe</h2>
          <p>[e-mail]</p>
        </div>
        <button on:click={() => screenController.goBack()}> Back to Dashboard </button>
      </div>
    </Screen>

    <!-- Settings Screen -->
    <Screen name="settings">
      <div class="screen-content settings">
        <h1>Settings</h1>
        <div class="settings-options">
          <div class="setting-item">
            <span>Dark Mode</span>
            <input type="checkbox" />
          </div>
          <div class="setting-item">
            <span>Notifications</span>
            <input type="checkbox" checked />
          </div>
          <div class="setting-item">
            <span>Sound</span>
            <input type="checkbox" />
          </div>
        </div>
        <button on:click={() => screenController.goBack()}> Save and Go Back </button>
      </div>
    </Screen>
  </ScreenStack>
</div>

<!-- Navigation controls -->
<div class="navigation-bar">
  <button on:click={() => screenController.changeScreen('dashboard')}>Dashboard</button>
  <button on:click={() => screenController.changeScreen('profile')}>Profile</button>
  <button on:click={() => screenController.changeScreen('settings')}>Settings</button>
  <button on:click={() => screenController.goBack()}>Back</button>
</div>

<style>
  .screen-container {
    width: 100%;
    height: 80vh;
    border: 1px solid #ccc;
    border-radius: 8px;
    overflow: hidden;
    position: relative;
  }

  .screen-content {
    height: 100%;
    width: 100%;
    padding: 20px;
    color: white;
    display: flex;
    flex-direction: column;
    justify-content: center;
    align-items: center;
    text-align: center;
  }

  .dashboard {
    background-color: #3498db;
  }

  .profile {
    background-color: #2ecc71;
  }

  .settings {
    background-color: #9b59b6;
  }

  .profile-info {
    margin: 20px 0;
  }

  .avatar {
    font-size: 4em;
    margin-bottom: 10px;
  }

  .settings-options {
    width: 80%;
    max-width: 300px;
    margin: 20px 0;
  }

  .setting-item {
    display: flex;
    justify-content: space-between;
    align-items: center;
    padding: 10px;
    border-bottom: 1px solid rgba(255, 255, 255, 0.2);
  }

  .navigation-bar {
    margin-top: 20px;
    display: flex;
    justify-content: center;
    flex-wrap: wrap;
    gap: 10px;
  }

  button {
    padding: 10px 20px;
    background-color: #333;
    color: white;
    border: none;
    border-radius: 5px;
    cursor: pointer;
    font-size: 14px;
  }

  button:hover {
    background-color: #555;
  }
</style>

This example creates a simple app with three screens: Dashboard, Profile, and Settings. Users can navigate between screens using either the navigation bar or buttons within each screen. The transitions between screens are animated with custom animations defined in the animation object.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an issue to improve this library.

See CONTRIBUTING.md for more information on how to contribute.