@motionscript/grids 0.0.0-stage → 0.1.0-alpha.4

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.
Files changed (133) hide show
  1. package/CHANGELOG.md +41 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +48 -0
  4. package/README.md +86 -3
  5. package/dist/browser/chunks/chunk-XDUDKWM7.js +2 -0
  6. package/dist/browser/chunks/chunk-XDUDKWM7.js.map +7 -0
  7. package/dist/browser/index.js +2 -0
  8. package/dist/browser/index.js.map +7 -0
  9. package/dist/browser/kit.js +2 -0
  10. package/dist/browser/kit.js.map +7 -0
  11. package/dist/browser/manifest.json +13 -0
  12. package/dist/engine.d.ts +13 -0
  13. package/dist/engine.d.ts.map +1 -0
  14. package/dist/engine.js +13 -0
  15. package/dist/engine.js.map +1 -0
  16. package/dist/index.d.ts +7 -0
  17. package/dist/index.d.ts.map +1 -0
  18. package/dist/index.js +7 -0
  19. package/dist/index.js.map +1 -0
  20. package/dist/kit/index.d.ts +7 -0
  21. package/dist/kit/index.d.ts.map +1 -0
  22. package/dist/kit/index.js +7 -0
  23. package/dist/kit/index.js.map +1 -0
  24. package/dist/kit/item-effects.d.ts +37 -0
  25. package/dist/kit/item-effects.d.ts.map +1 -0
  26. package/dist/kit/item-effects.js +76 -0
  27. package/dist/kit/item-effects.js.map +1 -0
  28. package/dist/kit/item-grid.d.ts +235 -0
  29. package/dist/kit/item-grid.d.ts.map +1 -0
  30. package/dist/kit/item-grid.js +519 -0
  31. package/dist/kit/item-grid.js.map +1 -0
  32. package/dist/kit/order.d.ts +13 -0
  33. package/dist/kit/order.d.ts.map +1 -0
  34. package/dist/kit/order.js +43 -0
  35. package/dist/kit/order.js.map +1 -0
  36. package/dist/kit/random.d.ts +7 -0
  37. package/dist/kit/random.d.ts.map +1 -0
  38. package/dist/kit/random.js +29 -0
  39. package/dist/kit/random.js.map +1 -0
  40. package/dist/kit/slots/index.d.ts +22 -0
  41. package/dist/kit/slots/index.d.ts.map +1 -0
  42. package/dist/kit/slots/index.js +28 -0
  43. package/dist/kit/slots/index.js.map +1 -0
  44. package/dist/kit/slots/path-templates.d.ts +15 -0
  45. package/dist/kit/slots/path-templates.d.ts.map +1 -0
  46. package/dist/kit/slots/path-templates.js +113 -0
  47. package/dist/kit/slots/path-templates.js.map +1 -0
  48. package/dist/kit/slots/path.d.ts +45 -0
  49. package/dist/kit/slots/path.d.ts.map +1 -0
  50. package/dist/kit/slots/path.js +87 -0
  51. package/dist/kit/slots/path.js.map +1 -0
  52. package/dist/kit/slots/radial.d.ts +30 -0
  53. package/dist/kit/slots/radial.d.ts.map +1 -0
  54. package/dist/kit/slots/radial.js +45 -0
  55. package/dist/kit/slots/radial.js.map +1 -0
  56. package/dist/kit/slots/rectangular.d.ts +42 -0
  57. package/dist/kit/slots/rectangular.d.ts.map +1 -0
  58. package/dist/kit/slots/rectangular.js +79 -0
  59. package/dist/kit/slots/rectangular.js.map +1 -0
  60. package/dist/kit/slots/slot.d.ts +62 -0
  61. package/dist/kit/slots/slot.d.ts.map +1 -0
  62. package/dist/kit/slots/slot.js +41 -0
  63. package/dist/kit/slots/slot.js.map +1 -0
  64. package/dist/kit/slots/sphere.d.ts +36 -0
  65. package/dist/kit/slots/sphere.d.ts.map +1 -0
  66. package/dist/kit/slots/sphere.js +68 -0
  67. package/dist/kit/slots/sphere.js.map +1 -0
  68. package/dist/kit/stagger.d.ts +24 -0
  69. package/dist/kit/stagger.d.ts.map +1 -0
  70. package/dist/kit/stagger.js +90 -0
  71. package/dist/kit/stagger.js.map +1 -0
  72. package/dist/nodes.d.ts +15 -0
  73. package/dist/nodes.d.ts.map +1 -0
  74. package/dist/nodes.js +15 -0
  75. package/dist/nodes.js.map +1 -0
  76. package/dist/path-grid/index.d.ts +2 -0
  77. package/dist/path-grid/index.d.ts.map +1 -0
  78. package/dist/path-grid/index.js +2 -0
  79. package/dist/path-grid/index.js.map +1 -0
  80. package/dist/path-grid/path-grid.d.ts +82 -0
  81. package/dist/path-grid/path-grid.d.ts.map +1 -0
  82. package/dist/path-grid/path-grid.js +192 -0
  83. package/dist/path-grid/path-grid.js.map +1 -0
  84. package/dist/radial-grid/index.d.ts +2 -0
  85. package/dist/radial-grid/index.d.ts.map +1 -0
  86. package/dist/radial-grid/index.js +2 -0
  87. package/dist/radial-grid/index.js.map +1 -0
  88. package/dist/radial-grid/radial-grid.d.ts +51 -0
  89. package/dist/radial-grid/radial-grid.d.ts.map +1 -0
  90. package/dist/radial-grid/radial-grid.js +95 -0
  91. package/dist/radial-grid/radial-grid.js.map +1 -0
  92. package/dist/rectangular-grid/index.d.ts +2 -0
  93. package/dist/rectangular-grid/index.d.ts.map +1 -0
  94. package/dist/rectangular-grid/index.js +2 -0
  95. package/dist/rectangular-grid/index.js.map +1 -0
  96. package/dist/rectangular-grid/rectangular-grid.d.ts +79 -0
  97. package/dist/rectangular-grid/rectangular-grid.d.ts.map +1 -0
  98. package/dist/rectangular-grid/rectangular-grid.js +156 -0
  99. package/dist/rectangular-grid/rectangular-grid.js.map +1 -0
  100. package/dist/sphere-grid/index.d.ts +2 -0
  101. package/dist/sphere-grid/index.d.ts.map +1 -0
  102. package/dist/sphere-grid/index.js +2 -0
  103. package/dist/sphere-grid/index.js.map +1 -0
  104. package/dist/sphere-grid/sphere-grid.d.ts +68 -0
  105. package/dist/sphere-grid/sphere-grid.d.ts.map +1 -0
  106. package/dist/sphere-grid/sphere-grid.js +149 -0
  107. package/dist/sphere-grid/sphere-grid.js.map +1 -0
  108. package/package.json +71 -3
  109. package/registry.json +32 -0
  110. package/src/engine.ts +12 -0
  111. package/src/index.ts +6 -0
  112. package/src/kit/index.ts +6 -0
  113. package/src/kit/item-effects.ts +114 -0
  114. package/src/kit/item-grid.ts +585 -0
  115. package/src/kit/order.ts +41 -0
  116. package/src/kit/random.ts +29 -0
  117. package/src/kit/slots/index.ts +39 -0
  118. package/src/kit/slots/path-templates.ts +120 -0
  119. package/src/kit/slots/path.ts +120 -0
  120. package/src/kit/slots/radial.ts +62 -0
  121. package/src/kit/slots/rectangular.ts +108 -0
  122. package/src/kit/slots/slot.ts +82 -0
  123. package/src/kit/slots/sphere.ts +94 -0
  124. package/src/kit/stagger.ts +96 -0
  125. package/src/nodes.ts +15 -0
  126. package/src/path-grid/index.ts +1 -0
  127. package/src/path-grid/path-grid.ts +213 -0
  128. package/src/radial-grid/index.ts +1 -0
  129. package/src/radial-grid/radial-grid.ts +90 -0
  130. package/src/rectangular-grid/index.ts +1 -0
  131. package/src/rectangular-grid/rectangular-grid.ts +160 -0
  132. package/src/sphere-grid/index.ts +1 -0
  133. package/src/sphere-grid/sphere-grid.ts +143 -0
@@ -0,0 +1,76 @@
1
+ /**
2
+ * What an item does on its way in (or out): grow from nothing, fade, fly out of
3
+ * the grid's centre, rise into place, flip up, or spin in.
4
+ */
5
+ export const REVEAL_STYLES = ["scale", "fade", "center", "rise", "flip", "spin"];
6
+ /** What a wave does to each item as it passes. */
7
+ export const WAVE_STYLES = ["scale", "lift", "fade", "spin"];
8
+ /** Layer item `i`'s reveal, wave and focus onto its slot, in place. */
9
+ export function applyItemEffects(s, i, size, reveal, wave, focus) {
10
+ if (reveal)
11
+ applyReveal(s, reveal.style, reveal.values[i] ?? 1, size);
12
+ if (wave)
13
+ applyWave(s, wave, wave.values[i] ?? 0, size);
14
+ if (focus)
15
+ applyFocus(s, focus, focus.values[i] ?? 0);
16
+ }
17
+ function applyReveal(s, style, v, size) {
18
+ if (v === 1)
19
+ return;
20
+ const shown = clamp01(v);
21
+ switch (style) {
22
+ case "fade":
23
+ s.opacity *= shown;
24
+ break;
25
+ case "center":
26
+ s.x *= v;
27
+ s.y *= v;
28
+ s.depth *= v;
29
+ s.opacity *= clamp01(v * 4);
30
+ break;
31
+ case "rise":
32
+ s.y -= (1 - v) * Math.max(40, size.height);
33
+ s.opacity *= shown;
34
+ break;
35
+ case "flip":
36
+ s.rotationX += (1 - v) * 90;
37
+ break;
38
+ case "spin":
39
+ s.rotation -= (1 - v) * 180;
40
+ s.scale *= Math.max(0, v);
41
+ break;
42
+ default:
43
+ s.scale *= Math.max(0, v);
44
+ }
45
+ }
46
+ function applyWave(s, wave, w, size) {
47
+ if (w === 0)
48
+ return;
49
+ switch (wave.style) {
50
+ case "lift":
51
+ s.y += wave.amount * w * Math.max(40, size.height);
52
+ break;
53
+ case "fade":
54
+ s.opacity *= clamp01(1 - wave.amount * w);
55
+ break;
56
+ case "spin":
57
+ s.rotation += wave.amount * w * 360;
58
+ break;
59
+ default:
60
+ s.scale *= 1 + wave.amount * w;
61
+ }
62
+ }
63
+ function applyFocus(s, focus, f) {
64
+ if (f === 0)
65
+ return;
66
+ if (f > 0) {
67
+ s.scale *= 1 + focus.grow * f;
68
+ return;
69
+ }
70
+ s.opacity *= clamp01(1 - focus.dim * -f);
71
+ s.scale *= Math.max(0, 1 + focus.grow * 0.5 * f);
72
+ }
73
+ function clamp01(v) {
74
+ return v < 0 ? 0 : v > 1 ? 1 : v;
75
+ }
76
+ //# sourceMappingURL=item-effects.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"item-effects.js","sourceRoot":"","sources":["../../src/kit/item-effects.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Size2D } from \"@motionscript/sdk\"\r\n\r\nimport type { Slot } from \"./slots\"\r\n\r\n/**\r\n * What an item does on its way in (or out): grow from nothing, fade, fly out of\r\n * the grid's centre, rise into place, flip up, or spin in.\r\n */\r\nexport const REVEAL_STYLES = [\"scale\", \"fade\", \"center\", \"rise\", \"flip\", \"spin\"] as const\r\nexport type RevealStyle = (typeof REVEAL_STYLES)[number]\r\n\r\n/** What a wave does to each item as it passes. */\r\nexport const WAVE_STYLES = [\"scale\", \"lift\", \"fade\", \"spin\"] as const\r\nexport type WaveStyle = (typeof WAVE_STYLES)[number]\r\n\r\n/**\r\n * How far into view each item is, `1` shown and `0` gone — past `1` on the\r\n * way to it under an overshooting ease. Absent means every item is shown.\r\n */\r\nexport interface RevealState {\r\n style: RevealStyle\r\n values: readonly number[]\r\n}\r\n\r\n/** Each item's share of the wave passing through it, `0` at rest and `1` at the crest. */\r\nexport interface WaveState {\r\n style: WaveStyle\r\n /** How big the crest is — a share of the item's size, opacity or a turn, by style. */\r\n amount: number\r\n values: readonly number[]\r\n}\r\n\r\n/** Each item's emphasis: `1` the focus, `-1` pushed back, `0` untouched. */\r\nexport interface FocusState {\r\n /** How far the others fade, `0..1`. */\r\n dim: number\r\n /** How much the focus grows, as a share of its size; the others shrink by half that. */\r\n grow: number\r\n values: readonly number[]\r\n}\r\n\r\n/** Layer item `i`'s reveal, wave and focus onto its slot, in place. */\r\nexport function applyItemEffects(\r\n s: Slot,\r\n i: number,\r\n size: Size2D,\r\n reveal: RevealState | null | undefined,\r\n wave: WaveState | null | undefined,\r\n focus: FocusState | null | undefined,\r\n): void {\r\n if (reveal) applyReveal(s, reveal.style, reveal.values[i] ?? 1, size)\r\n if (wave) applyWave(s, wave, wave.values[i] ?? 0, size)\r\n if (focus) applyFocus(s, focus, focus.values[i] ?? 0)\r\n}\r\n\r\nfunction applyReveal(s: Slot, style: RevealStyle, v: number, size: Size2D): void {\r\n if (v === 1) return\r\n const shown = clamp01(v)\r\n switch (style) {\r\n case \"fade\":\r\n s.opacity *= shown\r\n break\r\n case \"center\":\r\n s.x *= v\r\n s.y *= v\r\n s.depth *= v\r\n s.opacity *= clamp01(v * 4)\r\n break\r\n case \"rise\":\r\n s.y -= (1 - v) * Math.max(40, size.height)\r\n s.opacity *= shown\r\n break\r\n case \"flip\":\r\n s.rotationX += (1 - v) * 90\r\n break\r\n case \"spin\":\r\n s.rotation -= (1 - v) * 180\r\n s.scale *= Math.max(0, v)\r\n break\r\n default:\r\n s.scale *= Math.max(0, v)\r\n }\r\n}\r\n\r\nfunction applyWave(s: Slot, wave: WaveState, w: number, size: Size2D): void {\r\n if (w === 0) return\r\n switch (wave.style) {\r\n case \"lift\":\r\n s.y += wave.amount * w * Math.max(40, size.height)\r\n break\r\n case \"fade\":\r\n s.opacity *= clamp01(1 - wave.amount * w)\r\n break\r\n case \"spin\":\r\n s.rotation += wave.amount * w * 360\r\n break\r\n default:\r\n s.scale *= 1 + wave.amount * w\r\n }\r\n}\r\n\r\nfunction applyFocus(s: Slot, focus: FocusState, f: number): void {\r\n if (f === 0) return\r\n if (f > 0) {\r\n s.scale *= 1 + focus.grow * f\r\n return\r\n }\r\n s.opacity *= clamp01(1 - focus.dim * -f)\r\n s.scale *= Math.max(0, 1 + focus.grow * 0.5 * f)\r\n}\r\n\r\nfunction clamp01(v: number): number {\r\n return v < 0 ? 0 : v > 1 ? 1 : v\r\n}\r\n"]}
@@ -0,0 +1,235 @@
1
+ import { Node2D, type BoxBounds, type ChildPlacement, type Command, type CommandArgs, type MeasureContext2D, type EasingFunction, type Node2DProps, type Size2D, type SizeConstraints, type SpaceCamera } from "@motionscript/sdk";
2
+ export { findNode2D, frameIn } from "@motionscript/sdk";
3
+ import { type FocusState, type RevealState, type RevealStyle, type WaveState, type WaveStyle } from "./item-effects.js";
4
+ import { type Arrangement, type Slot } from "./slots/index.js";
5
+ import { type StaggerOrder } from "./stagger.js";
6
+ /** An arrangement a grid is leaving, kept as data so its slots can be worked out afresh every frame. */
7
+ export interface GridSnapshot {
8
+ arrangement: Arrangement;
9
+ /** The grid the arrangement was borrowed from, or `""` for the grid's own. */
10
+ source: string;
11
+ order: readonly number[];
12
+ spread: number;
13
+ }
14
+ /** A change of arrangement under way: where the items are coming from, and how far each has come. */
15
+ export interface GridTransition {
16
+ from: GridSnapshot;
17
+ /** Each item's eased, staggered progress, `0..1`. */
18
+ mix: readonly number[];
19
+ }
20
+ export interface ItemGridProps extends Node2DProps {
21
+ /** Items in slot order: slot `k` holds child `order[k]`. Empty is the children's own order. */
22
+ order: number[];
23
+ /** `0` gathers every item at the centre, `1` is the arrangement, past `1` pushes them apart. */
24
+ spread: number;
25
+ /** Another grid whose arrangement this one takes on — what {@link ItemGrid.morphInto} animates. */
26
+ arrangeLike: string;
27
+ revealState: RevealState | null;
28
+ waveState: WaveState | null;
29
+ focusState: FocusState | null;
30
+ transition: GridTransition | null;
31
+ }
32
+ /** What a command that moves the items to new slots is built from. */
33
+ export interface TransitionArgs {
34
+ data?: StaggerArgs;
35
+ duration: number;
36
+ easing?: EasingFunction;
37
+ }
38
+ /** The stagger options every per-item command takes. */
39
+ export interface StaggerArgs {
40
+ staggerOrder?: StaggerOrder;
41
+ /** `0..0.95`: how much of the command's length the items' offsets take up. */
42
+ stagger?: number;
43
+ }
44
+ /** `@command` descriptors for {@link StaggerArgs}, `stagger` defaulting to `fallback`. */
45
+ export declare function staggerArgs(fallback: number): readonly [{
46
+ readonly key: "staggerOrder";
47
+ readonly kind: "enum";
48
+ readonly options: readonly ["index", "reverse", "random", "centerOut", "edgesIn", "row", "column", "angle", "path", "depth"];
49
+ readonly default: "index";
50
+ }, {
51
+ readonly key: "stagger";
52
+ readonly min: 0;
53
+ readonly max: 0.95;
54
+ readonly step: 0.05;
55
+ readonly default: number;
56
+ }];
57
+ /**
58
+ * Every grid's document key — what a reference to "another grid" may name. A
59
+ * `nodeRef` descriptor carries it as `nodeTypes`, for a host's picker to offer
60
+ * only those.
61
+ */
62
+ export declare const ITEM_GRID_TYPES: readonly ["rectangularGrid", "radialGrid", "pathGrid", "sphereGrid"];
63
+ /** The stagger a move to new slots takes when its command states none. */
64
+ export declare const TRANSITION_STAGGER = 0.3;
65
+ /**
66
+ * The base of every grid: a container that places each of its children in a
67
+ * slot of an arrangement — a rectangular grid, a ring, a path, a sphere.
68
+ *
69
+ * ## Children only
70
+ *
71
+ * The items are the children, in layer order. A child's slot is a parent
72
+ * transform on it, so its own `x`/`y`/`rotation`/`scale` — and any command on
73
+ * them — still work, relative to the slot. A group is one item; a grid of
74
+ * grids is a grid of items that happen to be grids.
75
+ *
76
+ * ## One pass
77
+ *
78
+ * Every frame: measure the children, ask the arrangement for its slots (a pure
79
+ * function of the props, the sizes and the clock), blend them from where a
80
+ * transition is leaving, and layer on the per-item effects — reveal, wave,
81
+ * focus. What is left is each child's box and {@link ChildPlacement}, which the
82
+ * renderer, picking and `global` all read, so a selection outline lands on
83
+ * the pixels even on a sphere.
84
+ *
85
+ * ## Commands
86
+ *
87
+ * Every command is a pure function of time, like the rest of the library. The
88
+ * per-item ones stagger *inside* their duration — a one-second reveal takes one
89
+ * second for four children or four hundred — and write their per-item state
90
+ * into props ({@link revealState} and its siblings), which is what keeps them
91
+ * seekable. The ones that change the arrangement itself (a reorder, a morph, a
92
+ * column count) keep the arrangement they are leaving as data and blend each
93
+ * item from its old slot to its new one.
94
+ */
95
+ export declare abstract class ItemGrid<P extends ItemGridProps = ItemGridProps> extends Node2D<P> {
96
+ order: number[];
97
+ spread: number;
98
+ arrangeLike: string;
99
+ revealState: RevealState | null | undefined;
100
+ waveState: WaveState | null | undefined;
101
+ focusState: FocusState | null | undefined;
102
+ transition: GridTransition | null | undefined;
103
+ /**
104
+ * Bring the items in, one after another. Every item starts hidden, so place
105
+ * it where the grid enters — or after a {@link conceal}.
106
+ */
107
+ reveal(args: CommandArgs<{
108
+ style?: RevealStyle;
109
+ } & StaggerArgs> & {
110
+ duration: number;
111
+ }): Command<ItemGridProps>;
112
+ /** Take the items out, one after another — {@link reveal} in reverse. They stay hidden after. */
113
+ conceal(args: CommandArgs<{
114
+ style?: RevealStyle;
115
+ } & StaggerArgs> & {
116
+ duration: number;
117
+ }): Command<ItemGridProps>;
118
+ /** Send a ripple through the items that swells each in turn and settles back. */
119
+ wave(args: CommandArgs<{
120
+ style?: WaveStyle;
121
+ amount?: number;
122
+ } & StaggerArgs> & {
123
+ duration: number;
124
+ }): Command<ItemGridProps>;
125
+ /** Bring one item (by its place in the layers, from 0) forward and push the rest back. */
126
+ focus(args: CommandArgs<{
127
+ item?: number;
128
+ dim?: number;
129
+ grow?: number;
130
+ }> & {
131
+ duration: number;
132
+ }): Command<ItemGridProps>;
133
+ /** Bring every item back to even. */
134
+ unfocus(args: CommandArgs<Record<string, never>> & {
135
+ duration: number;
136
+ }): Command<ItemGridProps>;
137
+ /** Gather the items toward the centre (`0`), back to the arrangement (`1`), or push them apart. */
138
+ spreadTo(args: CommandArgs<{
139
+ spread: number;
140
+ }> & {
141
+ duration: number;
142
+ }): Command<P>;
143
+ /** Send every item to a random slot. The same `seed` always deals the same way. */
144
+ shuffle(args: CommandArgs<{
145
+ seed?: number;
146
+ } & StaggerArgs> & {
147
+ duration: number;
148
+ }): Command<P>;
149
+ /** Two items trade places, by their place in the layers. */
150
+ swap(args: CommandArgs<{
151
+ first?: number;
152
+ second?: number;
153
+ } & StaggerArgs> & {
154
+ duration: number;
155
+ }): Command<P>;
156
+ /** Move the items into a new order — a list of layer indices, first slot first, like `"2, 0, 1"`. */
157
+ reorder(args: CommandArgs<{
158
+ order?: string | number[];
159
+ } & StaggerArgs> & {
160
+ duration: number;
161
+ }): Command<P>;
162
+ /**
163
+ * Move every item into another grid's arrangement — a grid into a ring, a ring
164
+ * onto a sphere — and keep following it. An empty `target` morphs back to
165
+ * this grid's own.
166
+ */
167
+ morphInto(args: CommandArgs<{
168
+ target?: string;
169
+ } & StaggerArgs> & {
170
+ duration: number;
171
+ }): Command<P>;
172
+ /** This grid's own arrangement, for a content box of `box`. */
173
+ protected abstract arrangementFor(box: Size2D): Arrangement;
174
+ protected applyDefaultSize(props?: {
175
+ readonly width?: unknown;
176
+ readonly height?: unknown;
177
+ }): void;
178
+ /** The room each item is measured in — the whole content box, unless an arrangement has cells. */
179
+ protected itemSpace(_count: number, space: Size2D, _sizes?: readonly Size2D[]): Size2D;
180
+ measure(constraints: SizeConstraints, scope: MeasureContext2D): Partial<Size2D>;
181
+ protected layoutChildren(rect: BoxBounds, scope: MeasureContext2D): void;
182
+ _placementOf(child: Node2D): ChildPlacement | null;
183
+ /**
184
+ * A grid whose arrangement has depth is seen through a camera of its own,
185
+ * which paints its items far to near — unless it already sits in a space (an
186
+ * orbit camera, a 3D stage), where its items join that one and its camera.
187
+ */
188
+ _spaceCamera(): SpaceCamera | null;
189
+ private readonly _placements;
190
+ /** What {@link measure} found, for {@link layoutChildren} to reuse in the same pass. */
191
+ private _measured;
192
+ /** Each item's slot from the last layout — what a command ranks its stagger by. */
193
+ private _slots;
194
+ /** Each item's size from the last layout. */
195
+ private _sizes;
196
+ /** The last layout's camera distance, `0` while flat. */
197
+ private _focal;
198
+ private _borrowCache;
199
+ /** How many items a command built now will act on. */
200
+ protected _itemCount(): number;
201
+ /** Each item's slot as it stands, for a command being built — the last layout's where it still fits. */
202
+ protected _itemSlots(): Slot[];
203
+ /** The item sizes the last layout found. */
204
+ protected _itemSizes(): readonly Size2D[];
205
+ /** Each item's start in a stagger. A random order is seeded by the node's id, so it never changes between builds. */
206
+ protected _ranks(order: StaggerOrder | undefined): number[];
207
+ /**
208
+ * Write `changes` to the arrangement and move each item from its slot in the
209
+ * one being left to its slot in the new one, staggered.
210
+ */
211
+ protected _transitionTo(changes: Partial<P>, args: TransitionArgs, stagger?: number): Command<P>;
212
+ /** Emphasise the items `isFocus` picks and push the rest back. */
213
+ protected _focusOn(isFocus: (item: number) => boolean, count: number, args: CommandArgs<{
214
+ dim?: number;
215
+ grow?: number;
216
+ }> & {
217
+ duration: number;
218
+ }): Command<ItemGridProps>;
219
+ private _snapshot;
220
+ private _measureItems;
221
+ /** Where each item sits in the arrangement it is heading for, before any transition or effect. */
222
+ private _targetSlots;
223
+ /** Each item's final slot this frame: the target, blended from any transition, with its effects on. */
224
+ private _resolve;
225
+ /** Whether an ancestor places this grid in a space, as `spaceFrameOf` walks it. */
226
+ private _inSpace;
227
+ /** The grid {@link arrangeLike} names, when it names another grid in this tree. */
228
+ private _borrowed;
229
+ private _gridById;
230
+ /** `slots`, laid out in `source`'s frame, moved into this grid's. */
231
+ private _fromGrid;
232
+ }
233
+ /** A node's content box: its laid-out size inside its padding. */
234
+ export declare function contentBoxOf(grid: Node2D): Size2D;
235
+ //# sourceMappingURL=item-grid.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"item-grid.d.ts","sourceRoot":"","sources":["../../src/kit/item-grid.ts"],"names":[],"mappings":"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"}