@makefully/fancifully 0.1.0 → 0.3.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/CHANGELOG.md +50 -12
- package/LICENSE +21 -21
- package/README.md +245 -147
- package/dist/Storybook.d.ts +106 -3
- package/dist/Storybook.d.ts.map +1 -1
- package/dist/fancifully.css +1 -1
- package/dist/fancifully.iife.js +4 -8
- package/dist/fancifully.js +3538 -1999
- package/dist/flip/DefaultFlipStyle.d.ts +11 -0
- package/dist/flip/DefaultFlipStyle.d.ts.map +1 -0
- package/dist/flip/FlipStyle.d.ts +47 -0
- package/dist/flip/FlipStyle.d.ts.map +1 -0
- package/dist/flip/index.d.ts +4 -0
- package/dist/flip/index.d.ts.map +1 -0
- package/dist/index.d.ts +11 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/interop/fabricLike.d.ts +124 -0
- package/dist/interop/fabricLike.d.ts.map +1 -0
- package/dist/layout/layoutUnits.d.ts +43 -0
- package/dist/layout/layoutUnits.d.ts.map +1 -0
- package/dist/load/fanciFile.d.ts +6 -0
- package/dist/load/fanciFile.d.ts.map +1 -0
- package/dist/load/loadEpub.d.ts.map +1 -1
- package/dist/nav/Pager.d.ts +27 -5
- package/dist/nav/Pager.d.ts.map +1 -1
- package/dist/nav/hardback.d.ts +24 -0
- package/dist/nav/hardback.d.ts.map +1 -0
- package/dist/nav/layoutMode.d.ts +51 -4
- package/dist/nav/layoutMode.d.ts.map +1 -1
- package/dist/pack/packFanci.d.ts +16 -0
- package/dist/pack/packFanci.d.ts.map +1 -0
- package/dist/render/SpreadView.d.ts +67 -3
- package/dist/render/SpreadView.d.ts.map +1 -1
- package/dist/render/blocks/TextBlock.d.ts.map +1 -1
- package/dist/schema/story.d.ts +160 -17
- package/dist/schema/story.d.ts.map +1 -1
- package/dist/ui/iconifyIcon.d.ts +21 -0
- package/dist/ui/iconifyIcon.d.ts.map +1 -0
- package/package.json +76 -74
package/CHANGELOG.md
CHANGED
|
@@ -1,12 +1,50 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
All notable changes to this project will be documented in this file.
|
|
4
|
-
|
|
5
|
-
## [0.
|
|
6
|
-
|
|
7
|
-
### Added
|
|
8
|
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
11
|
-
-
|
|
12
|
-
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
## [0.3.0]
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- Reader layout on the host: `StorybookOptions.layoutMode` / `singleBreakpoint`, `setLayoutMode`, and `layoutPreference` (default `auto`)
|
|
10
|
+
- Authoring fields: `coverSize`, `guides`, cover `innerColor`, and text `fontWeight` / `fontStyle`
|
|
11
|
+
- Fabric-like page and spread interop, plus layout helpers (`boxToPixels`, `scaleBlocksToPageSize`)
|
|
12
|
+
- Package and page APIs: `packFanci`, `downloadFanci`, `addPage`, cover/hardback setters, and `setStageZoom`
|
|
13
|
+
|
|
14
|
+
### Changed
|
|
15
|
+
|
|
16
|
+
- Single vs two-page presentation is a reader setting. Stories store pages only; a legacy `layout` object in story JSON is ignored.
|
|
17
|
+
- The Maker UI and demo app left this package. Fabric is no longer a dependency.
|
|
18
|
+
- Chrome buttons use Iconify icons.
|
|
19
|
+
|
|
20
|
+
### Removed
|
|
21
|
+
|
|
22
|
+
- In-repo editor and demo (`src/editor`, `vite.demo.config.ts`)
|
|
23
|
+
|
|
24
|
+
## [0.2.0]
|
|
25
|
+
|
|
26
|
+
### Added
|
|
27
|
+
|
|
28
|
+
- Story `hardback` flag: larger front/back cover boards with a visible cover rim when interior pages are open
|
|
29
|
+
- Chrome theming: CSS vars for captions/buttons, image-button hooks (`--fc-btn-*-image` + `.fc-chrome--images`)
|
|
30
|
+
- `StorybookOptions.chrome` for labels, aria-labels, className, and hidden chrome
|
|
31
|
+
- Prev/next disable at first/last spread
|
|
32
|
+
- Layout modes: dedicated one-page spreads, `responsive` (orientation), remapping across mode flips
|
|
33
|
+
- `frontCover` / `backCover` story flags: closed centered covers; open/close via page-flip to interior (covers excluded from open spreads)
|
|
34
|
+
- Extensible `FlipStyle` API: `StorybookOptions.flipStyle` / `flipSpeed`, `registerFlipStyle`, built-in `DefaultFlipStyle`
|
|
35
|
+
- Optional `editor: true` host mode (Fabric page editing, cover toggles, `.fanci` download)
|
|
36
|
+
|
|
37
|
+
### Changed
|
|
38
|
+
|
|
39
|
+
- Flip style/speed are host-only (`StorybookOptions` / `setFlipStyle` / `setFlipSpeed`); removed from story JSON
|
|
40
|
+
- `single` builds one spread per story page (blank mate); `two-page` keeps facing pairs
|
|
41
|
+
- `auto` remains the width-breakpoint resolver; prefer `responsive` for device orientation
|
|
42
|
+
|
|
43
|
+
## [0.1.0]
|
|
44
|
+
|
|
45
|
+
### Added
|
|
46
|
+
|
|
47
|
+
- Initial `@makefully/fancifully` release: DOM storybook engine with JSON / `.fanci` / EPUB loading
|
|
48
|
+
- Unified two-leaf spread paging (single viewport uses blank offscreen mate)
|
|
49
|
+
- SpringRoll volume/pause/captions binding and load `progress` / `loading` / delayed `loaded`
|
|
50
|
+
- VO↔text sync via WebVTT or inline cues; text, image, and hotspot blocks
|
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 Makefully Studios
|
|
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.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Makefully Studios
|
|
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,147 +1,245 @@
|
|
|
1
|
-
# @makefully/fancifully
|
|
2
|
-
|
|
3
|
-
DOM-based interactive storybook engine with SpringRoll-friendly audio buses, VO↔text cue sync, hotspots, and a unified two-leaf page flip (single-page mode keeps a blank leaf offscreen so turns animate the same way).
|
|
4
|
-
|
|
5
|
-
## Install
|
|
6
|
-
|
|
7
|
-
```bash
|
|
8
|
-
npm install @makefully/fancifully
|
|
9
|
-
# optional peer for host mute/volume/captions
|
|
10
|
-
npm install springroll
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
## Publishing (maintainers)
|
|
14
|
-
|
|
15
|
-
Releases match other Makefully packages (`@makefully/platypus`, `@makefully/notefully`):
|
|
16
|
-
|
|
17
|
-
1. Bump `version` in `package.json` and add a `## [x.y.z]` section in `CHANGELOG.md`.
|
|
18
|
-
2. Merge to `main` (or run the **Release** workflow manually).
|
|
19
|
-
3. GitHub Actions tests, builds, publishes to npm via **OIDC trusted publisher**, and creates a GitHub release.
|
|
20
|
-
|
|
21
|
-
One-time npm setup (org owner): on [npmjs.com](https://www.npmjs.com) → `@makefully` → **Trusted Publishers** → add GitHub Actions for repo `Makefully-Studios/fancifully`, workflow `release.yml`, environment blank / as configured.
|
|
22
|
-
|
|
23
|
-
Local dry-run: `npm run pack:check`
|
|
24
|
-
|
|
25
|
-
## Quick start (standalone)
|
|
26
|
-
|
|
27
|
-
```ts
|
|
28
|
-
import { Storybook } from '@makefully/fancifully';
|
|
29
|
-
import '@makefully/fancifully/fancifully.css';
|
|
30
|
-
|
|
31
|
-
const book = await Storybook.create(document.getElementById('app')!, {
|
|
32
|
-
story: './stories/demo/story.json', // or './book.fanci' / './book.epub' / File
|
|
33
|
-
baseUrl: './stories/demo/', // used for loose JSON + relative assets
|
|
34
|
-
});
|
|
35
|
-
|
|
36
|
-
book.next();
|
|
37
|
-
book.prev();
|
|
38
|
-
book.playReadAloud();
|
|
39
|
-
book.setLayoutMode('
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
await Storybook.create(el, {
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
|
115
|
-
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
1
|
+
# @makefully/fancifully
|
|
2
|
+
|
|
3
|
+
DOM-based interactive storybook engine with SpringRoll-friendly audio buses, VO↔text cue sync, hotspots, and a unified two-leaf page flip (single-page mode keeps a blank leaf offscreen so turns animate the same way).
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @makefully/fancifully
|
|
9
|
+
# optional peer for host mute/volume/captions
|
|
10
|
+
npm install springroll
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Publishing (maintainers)
|
|
14
|
+
|
|
15
|
+
Releases match other Makefully packages (`@makefully/platypus`, `@makefully/notefully`):
|
|
16
|
+
|
|
17
|
+
1. Bump `version` in `package.json` and add a `## [x.y.z]` section in `CHANGELOG.md`.
|
|
18
|
+
2. Merge to `main` (or run the **Release** workflow manually).
|
|
19
|
+
3. GitHub Actions tests, builds, publishes to npm via **OIDC trusted publisher**, and creates a GitHub release.
|
|
20
|
+
|
|
21
|
+
One-time npm setup (org owner): on [npmjs.com](https://www.npmjs.com) → `@makefully` → **Trusted Publishers** → add GitHub Actions for repo `Makefully-Studios/fancifully`, workflow `release.yml`, environment blank / as configured.
|
|
22
|
+
|
|
23
|
+
Local dry-run: `npm run pack:check`
|
|
24
|
+
|
|
25
|
+
## Quick start (standalone)
|
|
26
|
+
|
|
27
|
+
```ts
|
|
28
|
+
import { Storybook } from '@makefully/fancifully';
|
|
29
|
+
import '@makefully/fancifully/fancifully.css';
|
|
30
|
+
|
|
31
|
+
const book = await Storybook.create(document.getElementById('app')!, {
|
|
32
|
+
story: './stories/demo/story.json', // or './book.fanci' / './book.epub' / File
|
|
33
|
+
baseUrl: './stories/demo/', // used for loose JSON + relative assets
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
book.next();
|
|
37
|
+
book.prev();
|
|
38
|
+
book.playReadAloud();
|
|
39
|
+
book.setLayoutMode('responsive'); // reader setting: 'single' | 'two-page' | 'responsive' | 'auto'
|
|
40
|
+
book.setFlipSpeed(300);
|
|
41
|
+
book.setFlipStyle('default');
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Flip style & speed
|
|
45
|
+
|
|
46
|
+
Page turns go through a `FlipStyle` implementation. Flip style and speed are **host settings** on `Storybook.create` / the instance — not fields in story JSON.
|
|
47
|
+
|
|
48
|
+
| API | Role |
|
|
49
|
+
|-----|------|
|
|
50
|
+
| `StorybookOptions.flipStyle` | Id (`"default"`), `FlipStyle` subclass, or instance |
|
|
51
|
+
| `StorybookOptions.flipSpeed` | Duration in ms (default `400`) |
|
|
52
|
+
| `registerFlipStyle(id, Ctor)` | Expose a custom class for string lookup |
|
|
53
|
+
| `book.setFlipStyle` / `setFlipSpeed` | Change at runtime |
|
|
54
|
+
|
|
55
|
+
```ts
|
|
56
|
+
import { Storybook, FlipStyle, registerFlipStyle, type FlipContext } from '@makefully/fancifully';
|
|
57
|
+
|
|
58
|
+
class InstantFlipStyle extends FlipStyle {
|
|
59
|
+
static id = 'instant';
|
|
60
|
+
play(_ctx: FlipContext) {
|
|
61
|
+
return Promise.resolve(); // no animation
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
registerFlipStyle('instant', InstantFlipStyle);
|
|
66
|
+
|
|
67
|
+
await Storybook.create(el, {
|
|
68
|
+
story: './story.json',
|
|
69
|
+
flipStyle: InstantFlipStyle, // or 'instant' or new InstantFlipStyle()
|
|
70
|
+
flipSpeed: 200,
|
|
71
|
+
});
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Built-in: `DefaultFlipStyle` (`"default"`) — CSS 3D leaf turn. The engine uses the same `FlipStyle` base class for built-ins so new styles stay consistent.
|
|
75
|
+
|
|
76
|
+
### Reader layout
|
|
77
|
+
|
|
78
|
+
Single page vs facing spread is a **host setting**, like flip style. Stories store a list of pages. The reader decides how to pair them. Legacy `layout` objects in story JSON are ignored.
|
|
79
|
+
|
|
80
|
+
| API | Role |
|
|
81
|
+
|-----|------|
|
|
82
|
+
| `StorybookOptions.layoutMode` | `single`, `two-page`, `responsive`, or `auto` (default) |
|
|
83
|
+
| `StorybookOptions.singleBreakpoint` | Width where `auto` switches to two-page (default `900`) |
|
|
84
|
+
| `book.setLayoutMode` | Change at runtime |
|
|
85
|
+
| `book.layoutPreference` | The host mode, before it resolves |
|
|
86
|
+
| `book.layoutMode` | Resolved `single` or `two-page` |
|
|
87
|
+
|
|
88
|
+
- **`two-page`**: facing pairs. With a front cover, open spreads start after the cover.
|
|
89
|
+
- **`single`**: one story page per turn, with a blank mate kept offscreen so the flip stays the same.
|
|
90
|
+
- **`responsive`**: landscape (width ≥ height) → two-page; portrait → single.
|
|
91
|
+
- **`auto`**: two-page when the stage is at least `singleBreakpoint` wide.
|
|
92
|
+
|
|
93
|
+
When the resolved mode changes, spreads rebuild and the view jumps to the spread that contains the current page.
|
|
94
|
+
|
|
95
|
+
## Chrome theming
|
|
96
|
+
|
|
97
|
+
Built-in Prev / Read / Next live under `.fc-chrome`. Customize via CSS variables on `.fc-root` (or a host class) and optional `chrome` options:
|
|
98
|
+
|
|
99
|
+
```ts
|
|
100
|
+
await Storybook.create(el, {
|
|
101
|
+
story: './stories/demo/story.json',
|
|
102
|
+
baseUrl: './stories/demo/',
|
|
103
|
+
chrome: {
|
|
104
|
+
className: 'my-theme fc-chrome--images', // image mode hides button text
|
|
105
|
+
labels: { prev: 'Prev', read: 'Read', next: 'Next' },
|
|
106
|
+
ariaLabels: { prev: 'Previous page', read: 'Read aloud', next: 'Next page' },
|
|
107
|
+
// hidden: true, // host-owned nav calling book.prev() / next() / playReadAloud()
|
|
108
|
+
},
|
|
109
|
+
});
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
| Variable | Role |
|
|
113
|
+
|----------|------|
|
|
114
|
+
| `--fc-chrome-bg` / `--fc-chrome-fg` | Chrome bar colors |
|
|
115
|
+
| `--fc-captions-bg` / `--fc-captions-fg` / `--fc-captions-bottom` | Caption line |
|
|
116
|
+
| `--fc-btn-border` / `--fc-btn-hover-bg` | Text button chrome |
|
|
117
|
+
| `--fc-btn-read-bg` / `--fc-btn-read-fg` | Read button fill |
|
|
118
|
+
| `--fc-btn-prev-image` / `--fc-btn-next-image` / `--fc-btn-read-image` | `url("…")` for image buttons |
|
|
119
|
+
| `--fc-btn-image-size` | Hit target when using `.fc-chrome--images` |
|
|
120
|
+
|
|
121
|
+
Prev/next disable at the first/last spread (`disabled` + `.is-disabled`).
|
|
122
|
+
|
|
123
|
+
## Authoring / editor
|
|
124
|
+
|
|
125
|
+
This package is the **player + story API** (load/render/playback, programmatic page mutations, `packFanci`, fabric-like JSON ingest). The Maker UI (Fabric overlays, page list, themes) lives in sibling [`@makefully/fancifully-editor`](../fancifully-editor):
|
|
126
|
+
|
|
127
|
+
```ts
|
|
128
|
+
import { Storybook } from '@makefully/fancifully';
|
|
129
|
+
import { attachEditor } from '@makefully/fancifully-editor';
|
|
130
|
+
import '@makefully/fancifully/fancifully.css';
|
|
131
|
+
import '@makefully/fancifully-editor/editor.css';
|
|
132
|
+
|
|
133
|
+
const book = await Storybook.create(el, { story });
|
|
134
|
+
attachEditor(book, { enter: true });
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Write helpers on `Storybook` include `addPage`, `removePage`, `reorderPages`, `setFrontCover` / `setBackCover` / `setHardback`, `updatePage`, `replaceStory`, `downloadFanci`, plus leaf-host APIs for overlays (`getEditableLeaves`, `setPageViewsHidden`, `setNavLocked`).
|
|
138
|
+
|
|
139
|
+
## Embed with SpringRoll (Platypus-like)
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
import { Application } from 'springroll';
|
|
143
|
+
import { Storybook } from '@makefully/fancifully';
|
|
144
|
+
import '@makefully/fancifully/fancifully.css';
|
|
145
|
+
|
|
146
|
+
const app = new Application({
|
|
147
|
+
features: {
|
|
148
|
+
sound: true,
|
|
149
|
+
soundVolume: true,
|
|
150
|
+
vo: true,
|
|
151
|
+
voVolume: true,
|
|
152
|
+
sfx: true,
|
|
153
|
+
captions: true,
|
|
154
|
+
},
|
|
155
|
+
});
|
|
156
|
+
|
|
157
|
+
const book = await Storybook.create(container, {
|
|
158
|
+
story: myStoryObject, // or URL
|
|
159
|
+
baseUrl: '/books/hill/',
|
|
160
|
+
springroll: app,
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
book.on('pagechange', ({ pageIds, index, layoutMode }) => {
|
|
164
|
+
console.log(pageIds, index, layoutMode);
|
|
165
|
+
});
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
If `springroll` is omitted, Fancifully creates an `Application` (when the peer is available) and **holds SpringRoll `loaded` / `state.ready` until the story package is unpacked and assets are loaded** — same idea as Platypus waiting on preload before the container hides its loading UI.
|
|
169
|
+
|
|
170
|
+
While loading, Fancifully reports:
|
|
171
|
+
|
|
172
|
+
| Bellhop event | Payload |
|
|
173
|
+
|---------------|---------|
|
|
174
|
+
| `progress` | `number` 0–1 (classic Container loading bar) |
|
|
175
|
+
| `loading` | `{ stage, progress, count?, total?, detail? }` |
|
|
176
|
+
|
|
177
|
+
```ts
|
|
178
|
+
await Storybook.create(el, {
|
|
179
|
+
story: './book.fanci',
|
|
180
|
+
onProgress: ({ stage, progress }) => console.log(stage, progress),
|
|
181
|
+
});
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
## Story formats
|
|
185
|
+
|
|
186
|
+
| Input | Extension | Notes |
|
|
187
|
+
|-------|-----------|--------|
|
|
188
|
+
| Fancifully JSON | `.json` | Full fidelity; `baseUrl` resolves relative assets |
|
|
189
|
+
| Fancifully package | **`.fanci`** | ZIP of `story.json` + images/audio/vtt/fonts (relative paths). (`.fan` is already used by other software.) |
|
|
190
|
+
| EPUB | `.epub` | Import subset: spine pages, images, fonts/audio when present, Media Overlays → cues. No hotspots. |
|
|
191
|
+
|
|
192
|
+
```ts
|
|
193
|
+
// Packaged book
|
|
194
|
+
await Storybook.create(el, { story: './tales/hill.fanci' });
|
|
195
|
+
|
|
196
|
+
// EPUB (read-aloud if Media Overlays exist)
|
|
197
|
+
await Storybook.create(el, { story: fileInput.files[0], storyName: fileInput.files[0].name });
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
Pack a folder into `.fanci`:
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
npm run pack:fanci -- path/to/story-dir [out.fanci]
|
|
204
|
+
# or: node scripts/pack-fanci.mjs path/to/story-dir out.fanci
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
## Story JSON
|
|
208
|
+
|
|
209
|
+
Stories are JSON packages (not a single HTML document). Text may embed HTML; images/audio/vtt are asset references.
|
|
210
|
+
|
|
211
|
+
| Field | Purpose |
|
|
212
|
+
|-------|---------|
|
|
213
|
+
| `pageSize` | Authoring pixel size per leaf |
|
|
214
|
+
| `frontCover` | If true, first page is a closed cover (centered); opens with a tween; no blank to its left |
|
|
215
|
+
| `backCover` | If true, last page is a back cover (no blank to its right); can close centered at the end |
|
|
216
|
+
| `hardback` | If true (with a cover flag), cover boards are larger than interior pages so open spreads show a cover rim |
|
|
217
|
+
| `assets` | Map of image / audio / vtt / html |
|
|
218
|
+
| `pages[].blocks` | `text`, `image`, `hotspot` with `layout` boxes |
|
|
219
|
+
| `pages[].readAloud` | `{ audio, cues }` — cues are a VTT asset id or inline `{id,start,end}[]` |
|
|
220
|
+
|
|
221
|
+
`pages` is always a flat list. Facing pages are a reader presentation, not a stored spread.
|
|
222
|
+
|
|
223
|
+
### Covers (`frontCover` / `backCover` / `hardback`)
|
|
224
|
+
|
|
225
|
+
- **Unset (default):** book starts open with a blank mate beside the first page (`[blank, p0]`) and a trailing blank after an orphan last page.
|
|
226
|
+
- **`frontCover: true`:** starts closed (cover centered). Next **page-flips** to the first interior spread (cover is not kept on screen). Open spreads omit the cover page.
|
|
227
|
+
- **`backCover: true`:** last page is omitted from open spreads; Next from the last interior spread **page-flips** to a centered back cover.
|
|
228
|
+
- **`hardback: true`:** cover boards are slightly larger than `pageSize` (~3.5% per edge). Closed covers use that larger board; when open, cover art stays behind the interior spread so a rim remains visible.
|
|
229
|
+
|
|
230
|
+
### VO ↔ text
|
|
231
|
+
|
|
232
|
+
Put stable `id`s on spans in text HTML. WebVTT cue identifiers should match those ids. While VO plays, matching spans get `is-active` / `is-read`. A separate captions line respects SpringRoll `captionsMuted`.
|
|
233
|
+
|
|
234
|
+
## Scripts
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
npm install
|
|
238
|
+
npm test
|
|
239
|
+
npm run dev # demo app (Vite)
|
|
240
|
+
npm run build # dist library + types
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
## License
|
|
244
|
+
|
|
245
|
+
MIT
|
package/dist/Storybook.d.ts
CHANGED
|
@@ -1,8 +1,29 @@
|
|
|
1
|
+
import type { FlipStyleInput } from './flip/index.js';
|
|
2
|
+
import { findFanciFile } from './load/fanciFile.js';
|
|
3
|
+
import { type LoadedAssets } from './load/loadStory.js';
|
|
1
4
|
import type { StorySource } from './load/packageTypes.js';
|
|
5
|
+
import type { LayoutMode } from './nav/layoutMode.js';
|
|
2
6
|
import { type PagerEvents } from './nav/Pager.js';
|
|
3
|
-
import
|
|
7
|
+
import { type StageZoom } from './render/SpreadView.js';
|
|
8
|
+
import type { Story, StoryPage } from './schema/story.js';
|
|
4
9
|
import { type SpringrollLike } from './springroll/bindApplication.js';
|
|
5
10
|
import { type LoadProgress } from './springroll/loading.js';
|
|
11
|
+
export type StorybookChromeOptions = {
|
|
12
|
+
/** Hide built-in chrome (host can call next/prev/playReadAloud). */
|
|
13
|
+
hidden?: boolean;
|
|
14
|
+
/** Extra class(es) on `.fc-chrome` (e.g. `goldipup-chrome fc-chrome--images`). */
|
|
15
|
+
className?: string;
|
|
16
|
+
labels?: {
|
|
17
|
+
prev?: string;
|
|
18
|
+
read?: string;
|
|
19
|
+
next?: string;
|
|
20
|
+
};
|
|
21
|
+
ariaLabels?: {
|
|
22
|
+
prev?: string;
|
|
23
|
+
read?: string;
|
|
24
|
+
next?: string;
|
|
25
|
+
};
|
|
26
|
+
};
|
|
6
27
|
export type StorybookOptions = {
|
|
7
28
|
/** JSON URL/object, `.fanci` / `.epub` URL, or File/Blob/ArrayBuffer */
|
|
8
29
|
story: StorySource | Story;
|
|
@@ -14,6 +35,28 @@ export type StorybookOptions = {
|
|
|
14
35
|
autoPlayReadAloud?: boolean;
|
|
15
36
|
/** Extra progress listener (SpringRoll Container also receives progress/loading). */
|
|
16
37
|
onProgress?: (progress: LoadProgress) => void;
|
|
38
|
+
/** Built-in Prev / Read / Next chrome labels and visibility. */
|
|
39
|
+
chrome?: StorybookChromeOptions;
|
|
40
|
+
/**
|
|
41
|
+
* Page-flip style: registered id (`"default"`), a {@link FlipStyle} subclass,
|
|
42
|
+
* or an instance. Host setting (not part of story JSON).
|
|
43
|
+
*/
|
|
44
|
+
flipStyle?: FlipStyleInput;
|
|
45
|
+
/** Flip duration in milliseconds. Host setting (not part of story JSON). */
|
|
46
|
+
flipSpeed?: number;
|
|
47
|
+
/**
|
|
48
|
+
* How pages are presented: one at a time, facing pairs, by orientation, or
|
|
49
|
+
* by stage width. Host setting (not part of story JSON). Default `auto`.
|
|
50
|
+
*/
|
|
51
|
+
layoutMode?: LayoutMode;
|
|
52
|
+
/** Stage width in px where `auto` switches to two-page. Default 900. */
|
|
53
|
+
singleBreakpoint?: number;
|
|
54
|
+
};
|
|
55
|
+
export type EditableLeaf = {
|
|
56
|
+
side: 'left' | 'right';
|
|
57
|
+
pageIndex: number;
|
|
58
|
+
pageId: string;
|
|
59
|
+
slot: HTMLElement;
|
|
17
60
|
};
|
|
18
61
|
type StorybookEvents = PagerEvents & {
|
|
19
62
|
ready: {
|
|
@@ -40,22 +83,82 @@ export declare class Storybook {
|
|
|
40
83
|
private resizeObserver;
|
|
41
84
|
private listeners;
|
|
42
85
|
private destroyed;
|
|
86
|
+
private btnPrev;
|
|
87
|
+
private btnRead;
|
|
88
|
+
private btnNext;
|
|
89
|
+
private chromeHiddenByOptions;
|
|
90
|
+
/** Extra zip paths → bytes (fonts/images added by hosts/editors) for packFanci. */
|
|
91
|
+
private extraFiles;
|
|
92
|
+
private defaultFontFamily;
|
|
93
|
+
/** When true, swipe/keyboard/chrome nav and read-aloud are locked (editor overlay). */
|
|
94
|
+
private navLocked;
|
|
43
95
|
private constructor();
|
|
44
96
|
static create(container: HTMLElement, options: StorybookOptions): Promise<Storybook>;
|
|
45
97
|
get story(): Story;
|
|
46
|
-
get
|
|
98
|
+
get assets(): LoadedAssets;
|
|
99
|
+
get baseUrl(): string;
|
|
100
|
+
/** Mutable list of blob URLs owned by the loaded package (hosts may push). */
|
|
101
|
+
get blobUrls(): string[];
|
|
102
|
+
get layoutMode(): import("./index.js").ResolvedLayoutMode;
|
|
103
|
+
/** Host preference (`auto`, `responsive`, …) before it resolves to single or two-page. */
|
|
104
|
+
get layoutPreference(): LayoutMode;
|
|
47
105
|
get pageIds(): string[];
|
|
48
106
|
get spreadIndex(): number;
|
|
107
|
+
get isNavLocked(): boolean;
|
|
108
|
+
getDefaultFontFamily(): string | null;
|
|
109
|
+
setDefaultFontFamily(family: string | null): void;
|
|
110
|
+
getExtraFiles(): Record<string, Uint8Array>;
|
|
111
|
+
putExtraFile(path: string, bytes: Uint8Array): void;
|
|
112
|
+
/**
|
|
113
|
+
* Lock player navigation (swipe/keys/chrome) for overlay editors.
|
|
114
|
+
* When locked, also hides book chrome unless the host already hid it.
|
|
115
|
+
*/
|
|
116
|
+
setNavLocked(locked: boolean): void;
|
|
117
|
+
/** Visible content leaves for overlay editors (Fabric, etc.). */
|
|
118
|
+
getEditableLeaves(): EditableLeaf[];
|
|
119
|
+
/** The `.fc-spread` book element — host for a spread-wide editor overlay. */
|
|
120
|
+
getSpreadElement(): HTMLElement;
|
|
121
|
+
get bookState(): import("./index.js").BookState;
|
|
122
|
+
/** Left/right content pages for the current spread (`null` = blank leaf). */
|
|
123
|
+
getSpreadPages(): {
|
|
124
|
+
left: StoryPage | null;
|
|
125
|
+
right: StoryPage | null;
|
|
126
|
+
};
|
|
127
|
+
setPageViewsHidden(hidden: boolean): void;
|
|
128
|
+
remountCurrent(): void;
|
|
49
129
|
on<K extends keyof StorybookEvents>(event: K, fn: Listener<K>): () => void;
|
|
50
130
|
next(): Promise<void>;
|
|
51
131
|
prev(): Promise<void>;
|
|
52
132
|
goTo(pageId: string): Promise<void>;
|
|
133
|
+
/** Editor-only. Does not change single vs two-page layout. */
|
|
134
|
+
setStageZoom(zoom: StageZoom): void;
|
|
53
135
|
setLayoutMode(mode: LayoutMode): void;
|
|
136
|
+
setFlipStyle(style: FlipStyleInput): void;
|
|
137
|
+
setFlipSpeed(speedMs: number): void;
|
|
54
138
|
playReadAloud(): Promise<void>;
|
|
55
139
|
pause(): void;
|
|
56
140
|
resume(): void;
|
|
141
|
+
/** Replace the loaded story from a File / URL / Story object. */
|
|
142
|
+
replaceStory(source: StorySource | Story, storyName?: string): Promise<void>;
|
|
143
|
+
/** Open a `.fanci` File (validates extension/MIME). */
|
|
144
|
+
openFanciFile(file: File): Promise<void>;
|
|
145
|
+
/** Replace a page in-place and remount the current spread. */
|
|
146
|
+
updatePage(page: StoryPage): Promise<void>;
|
|
147
|
+
setPages(pages: StoryPage[], preferPageId?: string | null): Promise<void>;
|
|
148
|
+
addPage(): Promise<StoryPage>;
|
|
149
|
+
removePage(pageId: string): Promise<void>;
|
|
150
|
+
reorderPages(fromIndex: number, toIndex: number): Promise<void>;
|
|
151
|
+
setFrontCover(enabled: boolean): Promise<void>;
|
|
152
|
+
setBackCover(enabled: boolean): Promise<void>;
|
|
153
|
+
setHardback(enabled: boolean): Promise<void>;
|
|
154
|
+
/** Apply a font family to every text block in the story. */
|
|
155
|
+
applyFontToAllText(family: string): void;
|
|
156
|
+
packToBlob(): Promise<Blob>;
|
|
157
|
+
downloadFanci(filename?: string): Promise<void>;
|
|
57
158
|
destroy(): void;
|
|
159
|
+
private navigate;
|
|
58
160
|
private wireChrome;
|
|
161
|
+
private syncChromeNavState;
|
|
59
162
|
private wirePager;
|
|
60
163
|
private wireSpringroll;
|
|
61
164
|
private wireResize;
|
|
@@ -65,5 +168,5 @@ export declare class Storybook {
|
|
|
65
168
|
private handleTapActions;
|
|
66
169
|
private emit;
|
|
67
170
|
}
|
|
68
|
-
export {};
|
|
171
|
+
export { findFanciFile };
|
|
69
172
|
//# sourceMappingURL=Storybook.d.ts.map
|