From ec83a7d28dc01dd585423ec9b98d70b397c00b0c Mon Sep 17 00:00:00 2001 From: YeSuX <351490949@qq.com> Date: Thu, 18 Jan 2024 02:04:42 +0800 Subject: [PATCH] feat: add docs of motion --- .../motion/2.guide/1.animation/3.Gestures.md | 2 +- .../motion/2.guide/2.components/1.motion.md | 280 -------------- .../motion/3.api/1.components/1.motion.md | 362 ++++++++++++++++++ .../1.components}/2.presence.md | 0 .../1.components}/3.presence-group.md | 0 .../1.components}/_dir.yml | 0 .docs/content/motion/3.api/1.motion.md | 280 -------------- .docs/content/motion/3.api/2.presence.md | 168 -------- .../content/motion/3.api/3.presence-group.md | 18 - 9 files changed, 363 insertions(+), 747 deletions(-) delete mode 100644 .docs/content/motion/2.guide/2.components/1.motion.md create mode 100644 .docs/content/motion/3.api/1.components/1.motion.md rename .docs/content/motion/{2.guide/2.components => 3.api/1.components}/2.presence.md (100%) rename .docs/content/motion/{2.guide/2.components => 3.api/1.components}/3.presence-group.md (100%) rename .docs/content/motion/{2.guide/2.components => 3.api/1.components}/_dir.yml (100%) delete mode 100644 .docs/content/motion/3.api/1.motion.md delete mode 100644 .docs/content/motion/3.api/2.presence.md delete mode 100644 .docs/content/motion/3.api/3.presence-group.md diff --git a/.docs/content/motion/2.guide/1.animation/3.Gestures.md b/.docs/content/motion/2.guide/1.animation/3.Gestures.md index cfb29e3..d96eac9 100644 --- a/.docs/content/motion/2.guide/1.animation/3.Gestures.md +++ b/.docs/content/motion/2.guide/1.animation/3.Gestures.md @@ -16,6 +16,6 @@ It currently has support for hover, press and more. Each gesture has a series of The hover gesture detects when a pointer hovers a component. diff --git a/.docs/content/motion/2.guide/2.components/1.motion.md b/.docs/content/motion/2.guide/2.components/1.motion.md deleted file mode 100644 index 593c27d..0000000 --- a/.docs/content/motion/2.guide/2.components/1.motion.md +++ /dev/null @@ -1,280 +0,0 @@ ---- -title: Motion -description: Renders an animatable HTML or SVG element. -icon: i-ph-brackets-curly-duotone ---- - -Renders an animatable HTML or SVG element. - -```ts - -``` - -# Usage -Import Motion from "@oku-ui/motion" and register it with your component. - - -```ts - - - - - -``` - -Motion accepts an animate prop. Add the following to the editable example above: - -``` - -``` - -The animate prop accepts all the same values and keyframes as Motion One's [animate](https://motion.dev/dom/animate) function. - - -## Transition settings - -We can change the type of animation used by passing a `transition` prop. - -```ts - - -``` - -By default transition options are applied to all values, but we can also override on a per-value basis: - -```ts - - -``` - -All the same transition options from Motion One's [animate function](https://motion.dev/dom/animate#options) are accepted. You can even import custom easing from Motion One, like [spring](https://motion.dev/dom/spring): - -```ts - - - - - - - -``` - - -## Props - -### tag - -default: `div` - -Define a HTML or SVG tag to render. - -```ts - -``` - -### animate - -A target of values to animate to. - -``` - -``` - -Whenever a value in animate changes, the element will automatically animate to the latest value. - -The animate prop accepts all the same values and keyframes as Motion One's [animate function](https://motion.dev/dom/animate). - -### initial -A target of values to animate from when the element is first rendered. - -```ts - -``` - -If set to false, the target defined in animate will be immediately set when the element is first rendered. Only subsequent changes to animate will animate. - - -```ts - -``` - - -### exit - -A target of values to animate to when the element is hidden via v-if or v-show. - -The element must be a direct child of the Presence component. - -```ts - - - - - - -``` - -Note: This animation is only interruptible if the element is hidden via v-show. - -The exit prop accepts all the same values and keyframes as Motion One's [animate function](https://motion.dev/dom/animate). - -### transition - -Provides a default transition for all animations to use. - -```ts - - -``` - -Supports all [animate options.](https://motion.dev/dom/animate#options) - -The transition defined in this prop can be overridden for specific animation props by passing those a transition option: - -```ts - - -``` - -## Events - -The Motion components emit [custom DOM events](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events#adding_custom_data_%E2%80%93_customevent) to the rendered element. The detail prop is provided data on the related animation. - -```ts - - - - - -``` - -### motionstart - -Fires when any animation is started. - -### motioncomplete - -Fires when any animation is completed. - diff --git a/.docs/content/motion/3.api/1.components/1.motion.md b/.docs/content/motion/3.api/1.components/1.motion.md new file mode 100644 index 0000000..e5d8633 --- /dev/null +++ b/.docs/content/motion/3.api/1.components/1.motion.md @@ -0,0 +1,362 @@ +--- +title: Motion +description: Motion components are DOM primitives optimised for 60fps animation and gestures. +icon: i-ph-brackets-curly-duotone +--- + +There's a motion component for every HTML and SVG element, for instance ``, `` etc. + +These work exactly like their static counterparts, but offer props that allow you to: + +- Animate +- Add drag, pan, hover and tap gestures +- Respond to gestures and elements entering the viewport with animation +- Deeply animate throughout variants + +And much more. + +## Supported values + +### Value types + +Motion can animate: + +- Numbers: `0`, `10` etc. +- Strings containing numbers: `"0vh"`, `"10px"` etc. +- Colors: Hex, RGB, HSLA. +- Complex strings containing multiple numbers and/or colors (ie `"10px 0 #000"`) + +When animating to a non-animatable value like `"block"`, this value will be set instantly. By setting this value within `transitionEnd`, this value will be set at the end of the animation. + +```html + +``` + + + +### Value type conversion + +In general, values can only be animated between two of the same type (ie two `px`, two `%` etc). + +However, HTML component's `x`, `y`, `width`, `height`, `top`, `left`, `right` and `bottom` values have enhanced support and can all be animated freely between different value types. + +```html + +``` + + + +Additionally, any color type (hex, HSL, RGB) can animate between each other. + +### Transform + +Transform properties are accelerated by the GPU, and therefore animate smoothly. They can be set and animated individually as: + +- Translate shortcuts: `x`, `y`, `z` +- Translate: `translateX`, `translateY`, `translateZ` +- Scale: `scale`, `scaleX`, `scaleY` +- Rotate: `rotate`, `rotateX`, `rotateY`, `rotateZ` +- Skew: `skew`, `skewX`, `skewY` +- Perspective: `transformPerspective` + +`motion` components have enhanced `style` props, allowing you to set them individually there, too. + +```html + +``` + + + +**SVG note**: For SVG components, `x` and `y` attributes (as opposed to the transform style) can be set using `attrX` and `attrY` within animation props. + +### Transform origin + +`transform-origin` has three shortcut values that can be set and animated individually: + +- `originX` +- `originY` +- `originZ` + +If set as numbers, `originX` and `Y` default to a progress value between `0` and `1`. `originZ` defaults to pixels. + +```html + +``` + +### CSS variables + +Motion can animate the value of CSS variables, and also read CSS variables as animation targets. + +#### Using pre-defined CSS variables in animation + +HTML `motion` components can animate to and from CSS variables, as long as that variable is defined on a component ancestor. + +```html + +``` + + + +#### Animating CSS variables + +By defining and animating CSS variables, we can use a parent `motion` component to declaratively animate multiple DOM children. + +CSS variables are also of an arbitary type, so Motion can't infer their default type. You're able to animate `rotate` as a number because Motion understands that it should be set as deg, whereas `'--rotate'` needs to be explicitly set with the unit type, e.g. `'360deg'`. + +```html + +
  • + +``` + + + +### SVG line drawing +Line drawing animations can be created with many SVG elements using three special properties: `pathLength`, `pathSpacing` and `pathOffset`. + + + + +These are all set as a value between `0` and `1`, where `1` is the measured length of the path. + +Path animations are compatible with `circle`, `ellipse`, `line`, `path`, `polygon`, `polyline` and `rect` elements. + +### Performance + +Motion animates values outside the Vue render cycle for increased performance. + +Using MotionValues instead of state to update visual properties will also avoid re-renders. + +Where possible, animate just transform values and opacity, as they are GPU-accelerated. This way, you can animate hundreds of layers on modern mobile devices. + +```html +// GPU accelerated (fast) + + +// CPU drawing (slower) + +``` + +### Server-side rendering + +`motion` components are fully compatible with server-side rendering, meaning the initial state of a component will be reflected in the server-generated output. + +```html +// Server will output `translateX(100px)` + +``` + +#### Exceptions + +The following SVG values are not currently compatible with server-side rendering: `scale`, `rotate`, `pathLength`, `pathOffset` and `pathSpacing`. + +`scale` and `rotate` rely on the dynamic calculation of `transformOrigin` - `originX` and `originY` should be set as strings (either `px` or `%`) to support these server side. + +```html + +``` + +`path` values rely on the measurement of the overall path length. Setting `strokeDasharray` to `"0 1"` will hide the path until Motion can measure it. + +```html + +``` + +## Props + +### tag + +- default: `div` + +Define a HTML or SVG tag to render. + +```html +Button +``` + +### animate + +A target of values to animate to. + +```html +// As values + + +// As variant + + +// Multiple variants + + +// AnimationControls + +``` + +Whenever a value in animate changes, the element will automatically animate to the latest value. + +The animate prop accepts all the same values and keyframes as Motion One's [animate function](https://motion.dev/dom/animate). + +### initial +A target of values to animate from when the element is first rendered. + +```ts +// As values + + +// As variant + + +// Multiple variants + + +// As false (disable mount animation) + +``` + +If set to false, the target defined in animate will be immediately set when the element is first rendered. Only subsequent changes to animate will animate. + +### exit + +A target of values to animate to when the element is hidden via v-if or v-show. + +The element must be a direct child of the Presence component. + +```vue + + + +``` + +Note: This animation is only interruptible if the element is hidden via v-show. + +The exit prop accepts all the same values and keyframes as Motion One's [animate function](https://motion.dev/dom/animate). + +### transition + +Provides a default transition for all animations to use. + +```html + +``` + +Supports all [animate options.](https://motion.dev/dom/animate#options) + +The transition defined in this prop can be overridden for specific animation props by passing those a transition option: + +## Gestures + +Motion extends the basic set of event listeners provided by Vue with a simple yet powerful set of UI gesture recognisers. + +[Learn more](../../2.guide/1.animation/3.Gestures.md) + +## Events + +The Motion components emit [custom DOM events](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events#adding_custom_data_%E2%80%93_customevent) to the rendered element. The detail prop is provided data on the related animation. + +```vue + + + +``` + +### motionstart + +Fires when any animation is started. + +### motioncomplete + +Fires when any animation is completed. + diff --git a/.docs/content/motion/2.guide/2.components/2.presence.md b/.docs/content/motion/3.api/1.components/2.presence.md similarity index 100% rename from .docs/content/motion/2.guide/2.components/2.presence.md rename to .docs/content/motion/3.api/1.components/2.presence.md diff --git a/.docs/content/motion/2.guide/2.components/3.presence-group.md b/.docs/content/motion/3.api/1.components/3.presence-group.md similarity index 100% rename from .docs/content/motion/2.guide/2.components/3.presence-group.md rename to .docs/content/motion/3.api/1.components/3.presence-group.md diff --git a/.docs/content/motion/2.guide/2.components/_dir.yml b/.docs/content/motion/3.api/1.components/_dir.yml similarity index 100% rename from .docs/content/motion/2.guide/2.components/_dir.yml rename to .docs/content/motion/3.api/1.components/_dir.yml diff --git a/.docs/content/motion/3.api/1.motion.md b/.docs/content/motion/3.api/1.motion.md deleted file mode 100644 index 593c27d..0000000 --- a/.docs/content/motion/3.api/1.motion.md +++ /dev/null @@ -1,280 +0,0 @@ ---- -title: Motion -description: Renders an animatable HTML or SVG element. -icon: i-ph-brackets-curly-duotone ---- - -Renders an animatable HTML or SVG element. - -```ts - -``` - -# Usage -Import Motion from "@oku-ui/motion" and register it with your component. - - -```ts - - - - - -``` - -Motion accepts an animate prop. Add the following to the editable example above: - -``` - -``` - -The animate prop accepts all the same values and keyframes as Motion One's [animate](https://motion.dev/dom/animate) function. - - -## Transition settings - -We can change the type of animation used by passing a `transition` prop. - -```ts - - -``` - -By default transition options are applied to all values, but we can also override on a per-value basis: - -```ts - - -``` - -All the same transition options from Motion One's [animate function](https://motion.dev/dom/animate#options) are accepted. You can even import custom easing from Motion One, like [spring](https://motion.dev/dom/spring): - -```ts - - - - - - - -``` - - -## Props - -### tag - -default: `div` - -Define a HTML or SVG tag to render. - -```ts - -``` - -### animate - -A target of values to animate to. - -``` - -``` - -Whenever a value in animate changes, the element will automatically animate to the latest value. - -The animate prop accepts all the same values and keyframes as Motion One's [animate function](https://motion.dev/dom/animate). - -### initial -A target of values to animate from when the element is first rendered. - -```ts - -``` - -If set to false, the target defined in animate will be immediately set when the element is first rendered. Only subsequent changes to animate will animate. - - -```ts - -``` - - -### exit - -A target of values to animate to when the element is hidden via v-if or v-show. - -The element must be a direct child of the Presence component. - -```ts - - - - - - -``` - -Note: This animation is only interruptible if the element is hidden via v-show. - -The exit prop accepts all the same values and keyframes as Motion One's [animate function](https://motion.dev/dom/animate). - -### transition - -Provides a default transition for all animations to use. - -```ts - - -``` - -Supports all [animate options.](https://motion.dev/dom/animate#options) - -The transition defined in this prop can be overridden for specific animation props by passing those a transition option: - -```ts - - -``` - -## Events - -The Motion components emit [custom DOM events](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events#adding_custom_data_%E2%80%93_customevent) to the rendered element. The detail prop is provided data on the related animation. - -```ts - - - - - -``` - -### motionstart - -Fires when any animation is started. - -### motioncomplete - -Fires when any animation is completed. - diff --git a/.docs/content/motion/3.api/2.presence.md b/.docs/content/motion/3.api/2.presence.md deleted file mode 100644 index 9e6ccf9..0000000 --- a/.docs/content/motion/3.api/2.presence.md +++ /dev/null @@ -1,168 +0,0 @@ ---- -title: Presence -description: Perform exit animations in Vue. -icon: i-ph-brackets-curly-duotone ---- - - -```ts - - - - -``` - -# Usage -Import Motion from "@oku-ui/motion" and register it with your component. - - -```ts - - - - - -``` - -Now, when a child `Motion` component is hidden with `v-if` or `v-show`, it will animate to the target defined in `exit` prop. - -Note: Presence currently only supports a single rendered child. - - -## Animate between elements - -By passing a different `key` to multiple children and rendering just one at a time, we can animate between them at a given time. - - -```ts - - - - - -``` - -In the above example, each element has the position: absolute CSS rule so when the incoming element is rendered it doesn't conflict with the element animating away. - -In situations where this isn't possible, `:exitBeforeEnter="true"` can be set on Presence to ensure the exiting element animates out before the entering element is rendered. - - -## Props - -### initial - -default: `true` - -If `false`, will disable the first animation on all child `Motion` elements the first time `Presence` is rendered. - - -### exitBeforeEnter - -default: `false` - -If `true`, Presence will wait for the exiting element to finish animating out before animating in the next one. \ No newline at end of file diff --git a/.docs/content/motion/3.api/3.presence-group.md b/.docs/content/motion/3.api/3.presence-group.md deleted file mode 100644 index 0a87c24..0000000 --- a/.docs/content/motion/3.api/3.presence-group.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: PresenceGroup -description: Perform exit animations in Vue. Group multiple Motion components together. -icon: i-ph-brackets-curly-duotone ---- - - -```ts - - - -``` \ No newline at end of file