shatter-morph 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Hayrullah Zafer Yılmaz
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,175 @@
1
- # Temporary Holding Version
1
+ # shatter-morph
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Shatter any HTML element into 3D shards and rebuild it as another. Cards, images, tables, forms, SVG and canvas all work with one function call.
4
+
5
+ <p align="center">
6
+ <img src="docs/assets/demo.gif" width="800" alt="A card cracks and breaks into 3D shards that swirl around the stage and rebuild as a photo card, then a login form, then the first card again">
7
+ </p>
8
+
9
+ <p align="center">
10
+ <a href="https://hayrullah-zafer-yilmaz.github.io/shatter-morph/">Live demo</a> ·
11
+ <a href="docs/README.tr.md">Türkçe</a> ·
12
+ <a href="CHANGELOG.md">Changelog</a>
13
+ </p>
14
+
15
+ - **Works on every tag:** the effect uses real copies of your element, so there is no screenshot step and cross-origin images keep working.
16
+ - **Works with any stack:** a dependency-free core, Vue and React adapters, and a `<shatter-morph>` element for Angular, Svelte or plain HTML.
17
+ - **Real 3D pieces:** cracks, thick tumbling shards, dust and mist, with `vortex`, `burst` and `fall` motions.
18
+ - **Safe by default:** copies are inert, scripts and inline handlers are removed, and passwords are never copied.
19
+ - **Never leaves content hidden:** the real element comes back if the animation is interrupted, the tab is hidden or the element is removed.
20
+ - **Accessible:** respects `prefers-reduced-motion` and can be switched off globally.
21
+ - **Small:** about 9 KB gzipped, with no dependencies.
22
+
23
+ ## Install
24
+
25
+ ```bash
26
+ npm install shatter-morph
27
+ ```
28
+
29
+ Or use a script tag:
30
+
31
+ ```html
32
+ <script src="https://cdn.jsdelivr.net/npm/shatter-morph"></script>
33
+ ```
34
+
35
+ The script exposes `window.ShatterMorph` and registers the `<shatter-morph>` element.
36
+
37
+ ## Quick start
38
+
39
+ ```js
40
+ import { shatterIn, shatterOut, shatterTo, shatterUpdate } from 'shatter-morph';
41
+
42
+ shatterTo(document.querySelector('#card'), document.querySelector('#photo'));
43
+
44
+ shatterUpdate(price, () => {
45
+ price.textContent = '$48';
46
+ });
47
+
48
+ await shatterOut(banner, { motion: 'burst' }).finished;
49
+ await shatterIn(banner).finished;
50
+ ```
51
+
52
+ ## API
53
+
54
+ | Function | What it does |
55
+ | ------------------------------------- | ------------------------------------------------------------------ |
56
+ | `shatterTo(from, to, options?)` | Hides `from`, shows `to` and morphs between them |
57
+ | `shatterUpdate(el, update, options?)` | Runs `update`, sync or async, and morphs old content into new |
58
+ | `shatterOut(el, options?)` | Breaks the element apart and hides it |
59
+ | `shatterIn(el, options?)` | Shows the element and assembles it from shards |
60
+ | `prepareShatter(el, options?)` | Captures now and returns `play()`, for changes made by a framework |
61
+ | `setShatterEnabled(value)` | Turns the effect on or off globally |
62
+ | `isShatterEnabled()` | Returns the global setting |
63
+
64
+ Every animation returns a controller:
65
+
66
+ ```ts
67
+ const animation = shatterTo(first, second);
68
+
69
+ animation.finish();
70
+ animation.cancel();
71
+
72
+ const result = await animation.finished;
73
+ ```
74
+
75
+ `result` is `'finished'`, `'cancelled'` or `'skipped'`. Finishing jumps to the final state. Cancelling restores the previous state, except in `shatterUpdate`, where the new content stays.
76
+
77
+ ### Options
78
+
79
+ | Option | Type | Default | Description |
80
+ | ---------------------- | ---------------------------------------------------- | ------------ | ----------------------------------- |
81
+ | `duration` | `number` | `1800` | Length in milliseconds |
82
+ | `shards` | `number`, `'auto'` | `'auto'` | Number of pieces, up to 220 |
83
+ | `motion` | `'vortex'`, `'burst'`, `'fall'` | `'vortex'` | Flight path |
84
+ | `origin` | `'right'`, `'left'`, `'top'`, `'bottom'`, `'center'` | `'right'` | Where the break starts |
85
+ | `spread` | `number` | `1` | Size of the flight path |
86
+ | `depth` | `number` | Automatic | Shard thickness in pixels |
87
+ | `color` | `string` | `'#8f897f'` | Dust and mist color |
88
+ | `edgeColor` | `string` | Neutral gray | Shard edge and crack color |
89
+ | `dust` | `boolean`, `number` | `true` | Shows dust, or sets the amount |
90
+ | `mist` | `boolean` | `true` | Shows the mist trail |
91
+ | `cracks` | `boolean` | `true` | Shows crack lines |
92
+ | `zIndex` | `number` | Highest | Overlay stacking order |
93
+ | `seed` | `number` | Random | Repeats the same break pattern |
94
+ | `keepLayout` | `boolean` | `false` | Keeps the space of hidden elements |
95
+ | `respectReducedMotion` | `boolean` | `true` | Skips the effect for reduced motion |
96
+ | `onComplete` | `(result) => void` | None | Called when the animation ends |
97
+
98
+ ## Vue
99
+
100
+ The directive works on any tag and plays when its value changes:
101
+
102
+ ```vue
103
+ <script setup>
104
+ import { ref } from 'vue';
105
+ import { vShatter } from 'shatter-morph/vue';
106
+
107
+ const plan = ref('pro');
108
+ </script>
109
+
110
+ <template>
111
+ <section v-shatter="{ key: plan, motion: 'burst' }">
112
+ <PlanCard :plan="plan" />
113
+ </section>
114
+ </template>
115
+ ```
116
+
117
+ `v-shatter="plan"` also works without options. There is a component too:
118
+
119
+ ```vue
120
+ <Shatter :value="plan" tag="article" :options="{ shards: 80 }" @complete="onDone">
121
+ <PlanCard :plan="plan" />
122
+ </Shatter>
123
+ ```
124
+
125
+ ## React
126
+
127
+ ```jsx
128
+ import { Shatter } from 'shatter-morph/react';
129
+
130
+ <Shatter value={plan} as="section" options={{ motion: 'vortex' }}>
131
+ <PlanCard plan={plan} />
132
+ </Shatter>
133
+ ```
134
+
135
+ Other props go to the rendered element. `onShatterComplete` receives the result.
136
+
137
+ ## Web Component
138
+
139
+ Use this in Angular, Svelte or plain HTML. It shows one child at a time, whatever their tags are:
140
+
141
+ ```js
142
+ import { defineShatterMorphElement } from 'shatter-morph/element';
143
+
144
+ defineShatterMorphElement();
145
+ ```
146
+
147
+ ```html
148
+ <shatter-morph id="slides" motion="vortex" duration="1800">
149
+ <article data-name="plan">Plan</article>
150
+ <img id="photo" src="photo.jpg" alt="Photo" />
151
+ <form>Sign in</form>
152
+ </shatter-morph>
153
+ ```
154
+
155
+ ```js
156
+ slides.next();
157
+ slides.previous();
158
+ slides.show('photo');
159
+ ```
160
+
161
+ Attributes: `active`, `motion`, `origin`, `duration`, `shards`, `color`, `no-dust`, `no-mist` and `no-cracks`. The element fires `shatter-complete` when a change ends.
162
+
163
+ ## Limitations
164
+
165
+ - Iframes, embeds and audio players appear as empty boxes while the effect runs.
166
+ - Closed shadow roots show only their light DOM. Open shadow roots are supported.
167
+ - A WebGL canvas needs `preserveDrawingBuffer` to be copied.
168
+ - Effects on parent elements, such as a parent's transform, opacity or filter, are not copied.
169
+ - Very large canvases and videos are drawn at a lower resolution while the effect runs, to limit memory use.
170
+ - Very large elements skip the effect and switch instantly, to protect performance.
171
+ - Automated browser checks currently run in Chrome.
172
+
173
+ ## License
174
+
175
+ [MIT](LICENSE)
@@ -0,0 +1,3 @@
1
+
2
+ //# sourceMappingURL=chunk-ETHEVVRU.js.map
3
+ //# sourceMappingURL=chunk-ETHEVVRU.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-ETHEVVRU.js"}