react-native-spritestudio-ui 0.0.0-stage → 7.0.0-beta.1

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/src/uiState.ts ADDED
@@ -0,0 +1,256 @@
1
+ import type { SpriteStudioPlayer, SsLabelTable } from 'react-native-spritestudio'
2
+
3
+ /**
4
+ * A state a SpriteStudio button shows. By default each plays from the label of
5
+ * the same name in one animation, up to the frame before the next label.
6
+ */
7
+ export type SsUiState = 'normal' | 'hover' | 'pressed' | 'disabled' | 'focused'
8
+
9
+ /**
10
+ * The one state to show when several hold at once: `disabled` over `pressed`
11
+ * over `hover` over `focused`, and `normal` when none does.
12
+ */
13
+ export function ssUiStateOf(flags: {
14
+ disabled?: boolean
15
+ pressed?: boolean
16
+ hovered?: boolean
17
+ focused?: boolean
18
+ }): SsUiState {
19
+ if (flags.disabled) return 'disabled'
20
+ if (flags.pressed) return 'pressed'
21
+ if (flags.hovered) return 'hover'
22
+ if (flags.focused) return 'focused'
23
+ return 'normal'
24
+ }
25
+
26
+ const CHAINS: Readonly<Record<SsUiState, readonly SsUiState[]>> = {
27
+ normal: ['normal'],
28
+ hover: ['hover', 'normal'],
29
+ pressed: ['pressed', 'hover', 'normal'],
30
+ disabled: ['disabled', 'normal'],
31
+ focused: ['focused', 'normal'],
32
+ }
33
+
34
+ /**
35
+ * What a state plays instead of the label named after it: the section of
36
+ * `animation` that starts at `label`.
37
+ *
38
+ * With only `animation`, the whole of it. With only `label`, that label in the
39
+ * animation the states are read from. A section runs to the frame before the
40
+ * next label, or to the end of the animation.
41
+ */
42
+ export type SsUiClip = { animation: string; label?: string } | { animation?: string; label: string }
43
+
44
+ /** Per-state replacements for the labels named after the states. */
45
+ export type SsUiClips = Partial<Record<SsUiState, SsUiClip>>
46
+
47
+ export const SS_REDUCED_MOTION_LABEL = 'reduced_motion'
48
+
49
+ /** A section a state plays, and whether to hold its first frame rather than play it. */
50
+ export interface SsUiSection {
51
+ animation: string
52
+ startFrame: number
53
+ endFrame: number
54
+ hold: boolean
55
+ }
56
+
57
+ function labelFrameOf(table: SsLabelTable, label: string): number | null {
58
+ for (const entry of table.labels) {
59
+ if (entry.name === label) return entry.frame
60
+ }
61
+ if (label === '_start') return table.startFrame
62
+ if (label === '_end') return table.endFrame
63
+ return null
64
+ }
65
+
66
+ /**
67
+ * The section starting at `label` in `table`: to the frame before the next
68
+ * label — any label, the state names or not — or to the end of the animation.
69
+ * Null when the table has no `label`.
70
+ */
71
+ export function labelSectionOf(
72
+ table: SsLabelTable,
73
+ label: string
74
+ ): { startFrame: number; endFrame: number } | null {
75
+ const start = labelFrameOf(table, label)
76
+ if (start == null) return null
77
+ for (const entry of table.labels) {
78
+ if (entry.frame > start) return { startFrame: start, endFrame: entry.frame - 1 }
79
+ }
80
+ return { startFrame: start, endFrame: table.endFrame }
81
+ }
82
+
83
+ /**
84
+ * The section `state` plays in `animation`: the first of its chain that has a
85
+ * clip in `clips` or a label of its own name, or else the whole animation.
86
+ * Null when `tableOf` knows no `animation`.
87
+ *
88
+ * Under `reducedMotion` the section is held, except where it came from
89
+ * `normal` (or the whole animation `normal` falls back to) and `animation` has a
90
+ * `reduced_motion` label: that label's section plays instead.
91
+ *
92
+ * A clip that names an animation or a label the pack does not have is handed
93
+ * to `onMissingClip`, and the state goes on as if it had none.
94
+ */
95
+ export function resolveUiSection(
96
+ state: SsUiState,
97
+ options: {
98
+ animation: string
99
+ tableOf: (animation: string) => SsLabelTable | null
100
+ clips?: SsUiClips
101
+ reducedMotion?: boolean
102
+ onMissingClip?: (state: SsUiState, clip: SsUiClip) => void
103
+ }
104
+ ): SsUiSection | null {
105
+ const { animation, tableOf, clips = {}, reducedMotion = false, onMissingClip } = options
106
+ const base = tableOf(animation)
107
+ if (base == null) return null
108
+ let name = animation
109
+ let range: { startFrame: number; endFrame: number } | null = null
110
+ let source: SsUiState | null = null
111
+ for (const s of CHAINS[state]) {
112
+ const clip = clips[s]
113
+ if (clip != null) {
114
+ const clipName = clip.animation ?? animation
115
+ const table = clipName === animation ? base : tableOf(clipName)
116
+ range =
117
+ table == null
118
+ ? null
119
+ : clip.label == null
120
+ ? { startFrame: table.startFrame, endFrame: table.endFrame }
121
+ : labelSectionOf(table, clip.label)
122
+ if (range != null) {
123
+ name = clipName
124
+ source = s
125
+ break
126
+ }
127
+ onMissingClip?.(s, clip)
128
+ }
129
+ range = labelSectionOf(base, s)
130
+ if (range != null) {
131
+ source = s
132
+ break
133
+ }
134
+ }
135
+ range ??= { startFrame: base.startFrame, endFrame: base.endFrame }
136
+ if (reducedMotion && (source === 'normal' || source === null)) {
137
+ const calm = labelSectionOf(base, SS_REDUCED_MOTION_LABEL)
138
+ if (calm != null) return { animation, ...calm, hold: false }
139
+ }
140
+ return { animation: name, ...range, hold: reducedMotion }
141
+ }
142
+
143
+ /**
144
+ * Plays the section an {@link SsUiState} calls for on a `player` the host owns.
145
+ *
146
+ * {@link show} switches at once and plays the new section from its first
147
+ * frame, looping; the section that was playing is dropped. Under reduced
148
+ * motion it holds the section's first frame instead, stopped, so no event
149
+ * fires — except that `normal`, and the states that fall back to it, play the
150
+ * `reduced_motion` label's section when the animation has one.
151
+ *
152
+ * It takes the player's playback over: it selects animations, sets sections
153
+ * and the loop count, and plays and stops.
154
+ */
155
+ export class SsUiStateDriver {
156
+ /**
157
+ * The animation the states' labels are read from. When omitted, the one the
158
+ * player has selected the first time a state is shown, or else the pack's
159
+ * first.
160
+ */
161
+ readonly animation: string | undefined
162
+ readonly clips: SsUiClips
163
+
164
+ private base: string | null = null
165
+ private shownOn: object | null = null
166
+ private shownAnimation: string | null = null
167
+ private current: SsUiState | null = null
168
+ private reduced = false
169
+ private readonly reported = new Set<string>()
170
+
171
+ constructor(
172
+ readonly player: SpriteStudioPlayer,
173
+ options: { animation?: string; clips?: SsUiClips } = {}
174
+ ) {
175
+ this.animation = options.animation
176
+ this.clips = options.clips ?? {}
177
+ }
178
+
179
+ /** The state last shown, or null before one has been. */
180
+ get state(): SsUiState | null {
181
+ return this.current
182
+ }
183
+
184
+ /**
185
+ * Shows `state` — or nothing before the player has loaded a pack.
186
+ *
187
+ * Showing the state already shown, with the same `reducedMotion`, does
188
+ * nothing while the player still has the pack and the animation it was
189
+ * given, so it can be called on every change the player announces. After
190
+ * another load, or a switch made elsewhere, it shows the state again.
191
+ */
192
+ show(state: SsUiState, reducedMotion = false): void {
193
+ const player = this.player
194
+ const internal = player.internal
195
+ if (internal == null) return
196
+ if (
197
+ internal === this.shownOn &&
198
+ state === this.current &&
199
+ reducedMotion === this.reduced &&
200
+ player.currentAnimation === this.shownAnimation
201
+ ) {
202
+ return
203
+ }
204
+ this.shownOn = internal
205
+ this.current = state
206
+ this.reduced = reducedMotion
207
+
208
+ const names = player.getAnimationNames()
209
+ const base =
210
+ this.base != null && names.includes(this.base)
211
+ ? this.base
212
+ : (this.animation ?? player.currentAnimation ?? names[0])
213
+ if (base == null) return
214
+ this.base = base
215
+
216
+ const section = resolveUiSection(state, {
217
+ animation: base,
218
+ tableOf: (name) => player.getLabelTable(name),
219
+ clips: this.clips,
220
+ reducedMotion,
221
+ onMissingClip: (s, clip) => this.reportMissingClip(s, clip),
222
+ })
223
+ if (section == null) {
224
+ player.setAnimation(base)
225
+ return
226
+ }
227
+ this.shownAnimation = section.animation
228
+ if (!player.setAnimation(section.animation)) {
229
+ this.shownAnimation = null
230
+ return
231
+ }
232
+ player.setAnimationSection(section.startFrame, section.endFrame)
233
+ if (section.hold) {
234
+ player.stop()
235
+ } else {
236
+ player.setLoopCount(0)
237
+ player.play()
238
+ }
239
+ }
240
+
241
+ private reportMissingClip(state: SsUiState, clip: SsUiClip): void {
242
+ const key = `${state}|${clip.animation ?? ''}|${clip.label ?? ''}`
243
+ if (this.reported.has(key)) return
244
+ this.reported.add(key)
245
+ const what = [
246
+ clip.animation != null ? `animation '${clip.animation}'` : null,
247
+ clip.label != null ? `label '${clip.label}'` : null,
248
+ ]
249
+ .filter((part) => part != null)
250
+ .join(' with ')
251
+ console.warn(
252
+ `react-native-spritestudio-ui: the clip for ${state} names ${what}, which the loaded ` +
253
+ `pack does not have, so ${state} plays as if it had none.`
254
+ )
255
+ }
256
+ }