133 lines
5.5 KiB
Markdown
133 lines
5.5 KiB
Markdown
# @marp-team/marpit-svg-polyfill
|
|
|
|
[](https://circleci.com/gh/marp-team/marpit-svg-polyfill/)
|
|
[](https://codecov.io/gh/marp-team/marpit-svg-polyfill)
|
|
[](https://www.npmjs.com/package/@marp-team/marpit-svg-polyfill)
|
|
[](./LICENSE)
|
|
|
|
The polyfill for [the inline SVG slide][inline-svg] rendered by [Marpit].
|
|
|
|
[marpit]: https://github.com/marp-team/marpit
|
|
[inline-svg]: https://marpit.marp.app/inline-svg
|
|
|
|
### Supported browser
|
|
|
|
- [WebKit](#webkit) based browser: Safari and iOS browsers (including iOS Chrome, iOS Firefox, iOS Edge, and so on...)
|
|
|
|
## Usage
|
|
|
|
```html
|
|
<!-- Generated HTML by Marpit's inline SVG mode -->
|
|
<div class="marpit">
|
|
<svg viewBox="0 0 1280 720" data-marpit-svg="">
|
|
<foreignObject width="1280" height="720">
|
|
<section>...</section>
|
|
</foreignObject>
|
|
</svg>
|
|
</div>
|
|
|
|
<!-- After than, use polyfill through jsDelivr CDN -->
|
|
<script src="https://cdn.jsdelivr.net/npm/@marp-team/marpit-svg-polyfill/lib/polyfill.browser.js"></script>
|
|
```
|
|
|
|
## Why need?
|
|
|
|
### WebKit
|
|
|
|
[Marpit]'s [inline SVG slide][inline-svg] has a lot of advantages: No requires JavaScript, gives better performance for scaling, and has predicatable DOM structure.
|
|
|
|
But unfortunately, WebKit browser has not scaled the wrapped HTML correctly. It is caused from a long standing [bug 23113](https://bugs.webkit.org/show_bug.cgi?id=23113), and it does not resolved in the last 15 years.
|
|
|
|
|
|
|
|
> **Note**
|
|
> A brand-new SVG engine for WebKit called as [**"Layer-based SVG engine (LBSE)"**](https://blogs.igalia.com/nzimmermann/posts/2021-10-29-layer-based-svg-engine/) is currently under development, and it will finally bring glitch-free scaling without JS. (See also: [Status of the new SVG engine in WebKit](https://wpewebkit.org/blog/05-new-svg-engine.html))
|
|
>
|
|
> You can test LBSE in [Safari Technology Preview](https://developer.apple.com/safari/technology-preview/) by following these steps:
|
|
>
|
|
> 1. Install Safari Technology Preview
|
|
> 1. Run `defaults write com.apple.SafariTechnologyPreview IncludeInternalDebugMenu 1` in terminal
|
|
> 1. Open Safari Technology Preview
|
|
> 1. Turn on **"Layer-based SVG engine (LBSE)"** from "Debug" menu → "WebKit Internal Features"
|
|
> 1. Restart app
|
|
>
|
|
> marpit-svg-polyfill v2.1.0 and later will try to detect whether or not enabled LBSE, and does not apply polyfill if LBSE was available.
|
|
|
|
## Solutions
|
|
|
|
### For Webkit
|
|
|
|
#### Scaling
|
|
|
|
We try to simulate scaling and centering by applying `transform` / `transform-origin` style to Marpit `<section>` elements.
|
|
|
|
```html
|
|
<svg viewBox="0 0 1280 960">
|
|
<foreignObject width="1280" height="960">
|
|
<section style="transform-origin:0 0;transform:matrix(......);">
|
|
...
|
|
</section>
|
|
</foreignObject>
|
|
</svg>
|
|
```
|
|
|
|
marpit-svg-polyfill uses the result of `getScreenCTM()` method, so the polyfill will sacrifice "zero-JS slide", the key feature of inline SVG.
|
|
|
|
#### Repainting
|
|
|
|
WebKit browser would not trigger repainting even if modified the contents of slide. It becomes a problem when supporting the live preview feature in Marp tools.
|
|
|
|
Fortunately, [a genius already resolved this problem only in CSS!](https://stackoverflow.com/a/21947628) `transform:translateZ(0)` would trigger re-painting immidiately when modified contents.
|
|
|
|
#### Animation GIF
|
|
|
|
People like to put GIF animation in the slide. However, GIF in polyfilled slides have glitches. GIF updates only a cropped part somewhere.
|
|
|
|
Applying `transform:translateZ(0.0001px)` to each `<section>` elements within SVG is a magic to resolve that. 🪄
|
|
|
|
> **Warning**
|
|
> This style brings slightly blurred contents too. Our polyfill prefers to render animated contents correctly.
|
|
|
|
<!--
|
|
|
|
## Advanced
|
|
|
|
### Apply polyfill manually
|
|
|
|
You may pick out the logic of polyfill if you required. When called a picked function, it applies polyfill forcibly without browser detection.
|
|
|
|
```javascript
|
|
import { webkit } from '@marp-team/marpit-svg-polyfill'
|
|
|
|
const observer = () => {
|
|
// Apply polyfill for webkit forcibly
|
|
webkit()
|
|
|
|
window.requestAnimationFrame(observer)
|
|
}
|
|
|
|
document.addEventListener('DOMContentLoaded', observer)
|
|
```
|
|
|
|
#### Use case in Blink browsers
|
|
|
|
We have confirmed a similar rendering bug to WebKit in a few Blink based browsers. (e.g. Chrome 66, Electron 3.x. refs: [marp-team/marpit#35](https://github.com/marp-team/marpit/pull/35), [marp-team/marp-cli#15](https://github.com/marp-team/marp-cli/pull/15))
|
|
|
|
We are not applied polyfill for Blink browsers because [they are working toward to resolve this.](https://bugs.chromium.org/p/chromium/issues/detail?id=467484) But you may apply `webkit()` manually if you required.
|
|
|
|
-->
|
|
|
|
## Contributing
|
|
|
|
We are following [the contributing guideline of marp-team projects](https://github.com/marp-team/.github/blob/master/CONTRIBUTING.md). Please read these guidelines this before starting work in this repository.
|
|
|
|
## Author
|
|
|
|
Managed by [@marp-team](https://github.com/marp-team).
|
|
|
|
- <img src="https://github.com/yhatt.png" width="16" height="16"/> Yuki Hattori ([@yhatt](https://github.com/yhatt))
|
|
|
|
## License
|
|
|
|
This module releases under the [MIT License](LICENSE).
|