Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/arcticicestudio/arctic-landscape
An animated drawing of an arctic landscape
https://github.com/arcticicestudio/arctic-landscape
animation arctic arcticicestudio drawing hacktoberfest landscape nord popmotion pose react react-pose reactjs styled-components svg
Last synced: 2 months ago
JSON representation
An animated drawing of an arctic landscape
- Host: GitHub
- URL: https://github.com/arcticicestudio/arctic-landscape
- Owner: arcticicestudio
- License: other
- Created: 2019-01-05T13:23:52.000Z (about 6 years ago)
- Default Branch: develop
- Last Pushed: 2020-12-11T07:33:39.000Z (about 4 years ago)
- Last Synced: 2024-10-06T01:48:07.304Z (4 months ago)
- Topics: animation, arctic, arcticicestudio, drawing, hacktoberfest, landscape, nord, popmotion, pose, react, react-pose, reactjs, styled-components, svg
- Language: JavaScript
- Size: 4.61 MB
- Stars: 30
- Watchers: 2
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
An animated drawing of an arctic landscape
Arctic Landscape is an animated [React][] [SVG][mdn-svg] component with a flat, simple and elegant appearance.
It consists of lines that should convey the effect to be drawn by hand and fade-in fillings that are smoothly timed on each other.
The [“Aurora Borealis”][wiki-aurbor] (also called _northern lights_) uses a gentle gradient animation to imitate the shimmering light.
Next to the main [animation poses](#animation-pose) the component can be customized in aspects like the [total animation duration](#animation-duration) and [styles of the outlines](#additional-outlines-styles).
A callback function can be passed to be called when the [draw/erase animation has been completed](#animation-completion-callback).
It also allows to use a [custom SVG `` element for the _Aurora Borealis_ shimmering light](#aurora-borealis-gradient) effect.
The component is build and compatible with the awesome [styled-components][stc] and [React Pose][rp] projects.
It was mainly developed for the usage and integration with [Nord][], therefore all default colors are based on [Nord's color palettes][nord-docs-c].
## Quick Start
```sh
npm install --save react react-dom arctic-landscape styled-components react-pose
```
## Getting Started
### Installation
Add the package as dependency to your project:
```sh
npm install --save arctic-landscape
```
Run `npm install` from within the project root to bootstrap the project and install the development- and runtime dependencies. Note that **this will not install the required [styled-components][npm-stc] and [react-pose][npm-rp]** packages that are defined as [peer dependencies][nodejs-blog-peerdeps] and must be installed separately like described in the [peer dependencies](#peer-dependencies) section below.
#### Peer Dependencies
This package uses [Styled Components][stc-doc-api] and [React Pose][rp-doc-api] API functions that return [React][] components.
Therefore, next to [React][npm-r] and [React DOM][npm-rd], this package depends on the [styled-components][npm-stc] and [react-pose][npm-rp] packages defined as [peer dependencies][nodejs-blog-peerdeps].
Linux & macOS users can easily install all peer dependencies by using [npx][npm-npx], [introduced in `[email protected]`][npm-blog-npx], which comes [pre-bundled with **Node.js 8.2.0** or higher][npm-get]:
```sh
npx install-peerdeps arctic-landscape
```
When using **npm < 5.2.0**, _npx_ is not pre-bundled, but users can either simply install it globally and then run the above command or install the [install-peerdeps][npm-ipd] package locally/globally to let it handle the installation of all peer dependencies.
```sh
# Via local installation…
npm install install-peerdeps
./node_modules/.bin/install-peerdeps arctic-landscape
# …or globally.
npm install -g install-peerdeps
install-peerdeps arctic-landscape
```
#### Manually
All peer dependencies can also be installed manually (e.g. for users running a Microsoft Windows based system) by installing the correct version of each package:
```sh
# Show a list of all required peer dependencies
npm info "arctic-landscape@latest" peerDependencies
# Install all required peer dependencies
npm install --save arctic-landscape react react-dom react-pose styled-components
```
## Usage
Arctic Landscape can be used by importing the [default exported][mdn-export] React component `ArcticLandscape`.
```js
import React, { Component } from "react";
import ArcticLandscape from "arctic-landscape";
```
The component can now be placed somewhere in the render tree:
```jsx
// Within a simple function component…
const CustomFunctionComponent = props => (
);
// …or a class component.
class CustomFunctionComponent extends Component {
/* ... */
render() {
return (
);
}
}
```
**NOTE**: The component itself **doesn't define any sizing attributes** and inherits from the parent element like the `
` in the example above. Therefore it must be wrapped in a container to control the width and height of the component.
To trigger the animation change the passed `erase` animation pose to the `draw` animation, e.g. by using a [class-based component][r-docs-comp] and store the name of the current pose in the state that can be toggled through a function:
```jsx
import React, { Component } from "react";
import ArcticLandscape, { POSE_DRAW, POSE_ERASE } from "arctic-landscape";
class CustomFunctionComponent extends Component {
state = {
pose: POSE_ERASE
};
togglePose = () => this.setState(({ pose }) => ({ pose: pose === POSE_ERASE ? POSE_DRAW : POSE_ERASE }));
render() {
const { pose } = this.state;
return (
Toggle Animation Pose
);
}
}
```
Make sure to read the [React Pose documentation][rp-docs-gs] for more details if you're not already familiar with the animation concept with poses.
## Customization
The component can be customized through props. All available props are documented in more detail in the sections below.
### Aurora Borealis Gradient
> **Prop**: `auroraBorealisGleamGradientId`
> **Type**: string
> **Default**: `arctic-landscape-aurora-borealis-gleam`
> **Required**: No
The component renders a [Aurora Borealis][wiki-aurbor] that is filled with an animated [`` element][mdn-svg-lg] to imitate the shimmering light. It can be swapped out with another `` element by passing the ID of this element to the `auroraBorealisGleamGradientId` prop.
```js
```
**NOTE**: The custom `` element **must be available in the DOM where the component is rendered in**, otherwise the element with the given ID won't be rendered!
Also make sure to follow the SVG specification for the custom [`` element][mdn-svg-lg] which \*\*must be placed within a [`` element][mdn-svg-defs], otherwise it won't be recognized in the DOM.
For example, if you'd like to use a custom gradient with different colors, define a new `` element or React component and place the custom `` element in it, wrapped by a `` element. Afterwards make sure to **give it a unique ID** (`custom-gradient-element-id` in the example above) to be passed to the `auroraBorealisGleamGradientId` prop and render it in the same DOM like the `ArcticLandscape` component.
**CustomAuroraBorealisGradient.jsx**
```jsx
const CustomAuroraBorealisGradient = () => (
);
export default CustomAuroraBorealisGradient;
```
**App.jsx**
```jsx
import React, { Fragment } from "react";
import ArcticLandscape from "arctic-landscape";
import CustomAuroraBorealisGradient from "./CustomAuroraBorealisGradient";
const App = () => (
);
export default App;
```
The default `` element is implemented in the [`GleamGradient` component][gh-src-aurbor-gg].
### Animation Duration
> **Prop**: `duration`
> **Type**: number
> **Default**: `4000`(ms)
> **Required**: No
The total animation duration in milliseconds.
```js
```
### Animation Completion Callback
> **Prop**: `onAnimationComplete`
> **Type**: function
> **Default**: `() => {}`(noop)
> **Required**: No
The function that will be called when the pose animation has been completed.
```js
const handleAnimationCompletion = () => console.log("Arctic Landscape pose animation has been completed!");
;
```
### Additional Outlines Styles
> **Prop**: `outlineStyles`
> **Type**: [`css` object][stc-doc-api-css] or [style object][stc-doc-adv-sto]
> **Default**: `() => {}` (noop)
> **Required**: No
Allows to pass additional styles for all outlines of the vector graphic. Since Arctic Landscape is built with [styled-components][stc] this prop accepts either a object of the [`css`][stc-doc-api-css] API function or [style object][stc-doc-adv-sto].
```js
import { css } from "styled-components";
// Either use the `css` API…
const additionalCssStyles = css`
stroke-width: 1;
stroke: #5e81ac;
`;
//…or a simple style object.
const additionalObjectStyles = {
strokeWidth: 1,
stroke: "#5e81ac"
};
;
```
Note that this will **override the styles of all outlines**!
### Animation Pose
> **Prop**: `pose`
> **Type**: string
> **Default**: -
> **Required**: Yes
> **Values**: `draw`\|`erase`
The `pose` prop is currently the only required prop and defines the name of the actual animation pose.
This can either be `draw` or `erase` where the first one starts the drawing animation and makes the component visible while the second one "erases" all drawn lines and fillings again with a quick reverted animation of the `draw` pose.
Note that both animation pose names are also available as constants as [named exports][mdn-export]:
- `POSE_DRAW` — The name of the `draw` animation pose
- `POSE_ERASE` — The name of the `erase` animation pose
```js
import { POSE_DRAW, POSE_ERASE } from "arctic-landscape";
```
## Development Workflow
Run `npm install` from within the project root to bootstrap the project and install the development- and runtime dependencies.
The project is configured for the opinionated code formatter [Prettier][] which provides [integration support for many editors][prettier-doc-editors] to e.g. automatically format the source file on save.
### Building
A distribution build can be created with [Rollup][] by running
```sh
npm run build
```
Continuous integration builds are running at [Circle CI][circle-ci].
### Testing
#### Linting
JavaScript sources are linted with [ESLint][] using the [arcticicestudio][npm-esl-ais] configuration which can be run with
```sh
npm run lint:js
```
Markdown sources are linted with [remark-lint][npm-rml] using the [arcticicestudio-preset][npm-rml-ais] which can be run with
```sh
npm run lint:md
```
All linting tasks can be run with
```sh
npm run lint
```
## Contributing
Read the [contributing guide][gh-contrib] to learn about the development process and how to propose [enhancement suggestions][gh-contrib-enhancements] and [report bugs][gh-contrib-bug-reports], how to [submit pull requests][gh-contrib-pr] and the project's [styleguides][gh-contrib-styleguides], [branch organization][gh-contrib-branch-org] and [versioning][gh-contrib-versioning] model.
The guide also includes information about [minimal, complete, and verifiable examples][gh-contrib-mcve] and other ways to contribute to the project like [improving existing issues][gh-contrib-improve-issues] and [giving feedback on issues and pull requests][gh-contrib-feedback].
---
Copyright © 2019-present Arctic Ice Studio & Sven Greb
[circle-ci]: https://circleci.com/gh/arcticicestudio/arctic-landscape
[eslint]: https://eslint.org
[gh-contrib-branch-org]: https://github.com/arcticicestudio/arctic-landscape/blob/develop/CONTRIBUTING.md#branch-organization
[gh-contrib-bug-reports]: https://github.com/arcticicestudio/arctic-landscape/blob/develop/CONTRIBUTING.md#bug-reports
[gh-contrib-enhancements]: https://github.com/arcticicestudio/arctic-landscape/blob/develop/CONTRIBUTING.md#enhancement-suggestions
[gh-contrib-feedback]: https://github.com/arcticicestudio/arctic-landscape/blob/develop/CONTRIBUTING.md#give-feedback-on-issues-and-pull-requests
[gh-contrib-improve-issues]: https://github.com/arcticicestudio/arctic-landscape/blob/develop/CONTRIBUTING.md#improve-issues
[gh-contrib-mcve]: https://github.com/arcticicestudio/arctic-landscape/blob/develop/CONTRIBUTING.md#mcve
[gh-contrib-pr]: https://github.com/arcticicestudio/arctic-landscape/blob/develop/CONTRIBUTING.md#pull-requests
[gh-contrib-styleguides]: https://github.com/arcticicestudio/arctic-landscape/blob/develop/CONTRIBUTING.md#styleguides
[gh-contrib-versioning]: https://github.com/arcticicestudio/arctic-landscape/blob/develop/CONTRIBUTING.md#versioning
[gh-contrib]: https://github.com/arcticicestudio/arctic-landscape/blob/develop/CONTRIBUTING.md
[gh-src-aurbor-gg]: https://github.com/arcticicestudio/arctic-landscape/blob/develop/src/AuroraBorealis/styled/GleamGradient.jsx
[mdn-export]: https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export
[mdn-svg-defs]: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/defs
[mdn-svg-lg]: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/linearGradient
[mdn-svg]: https://developer.mozilla.org/en-US/docs/Web/SVG
[nodejs-blog-peerdeps]: https://nodejs.org/en/blog/npm/peer-dependencies
[nord-docs-c]: https://www.nordtheme.com/docs/colors
[nord]: https://www.nordtheme.com
[npm-blog-npx]: https://blog.npmjs.org/post/162869356040/introducing-npx-an-npm-package-runner
[npm-esl-ais]: https://www.npmjs.com/package/eslint-config-arcticicestudio
[npm-get]: https://www.npmjs.com/get-npm
[npm-ipd]: https://www.npmjs.com/package/install-peerdeps
[npm-npx]: https://www.npmjs.com/package/npx
[npm-r]: https://www.npmjs.com/package/react
[npm-rd]: https://www.npmjs.com/package/react-dom
[npm-rml-ais]: https://www.npmjs.com/package/remark-preset-lint-arcticicestudio
[npm-rml]: https://www.npmjs.com/package/remark-cli
[npm-rp]: https://www.npmjs.com/package/react-pose
[npm-stc]: https://www.npmjs.com/package/styled-components
[prettier-doc-editors]: https://prettier.io/docs/en/editors
[prettier]: https://prettier.io
[r-docs-comp]: https://reactjs.org/docs/react-component.html
[react]: https://reactjs.org
[rollup]: https://rollupjs.org
[rp-doc-api]: https://popmotion.io/pose/api
[rp-docs-gs]: https://popmotion.io/pose/learn/get-started
[rp]: https://popmotion.io/pose
[stc-doc-adv-sto]: https://www.styled-components.com/docs/advanced#style-objects
[stc-doc-api-css]: https://www.styled-components.com/docs/api#css
[stc-doc-api]: https://www.styled-components.com/docs/api
[stc]: https://www.styled-components.com
[wiki-aurbor]: https://en.wikipedia.org/wiki/Aurora