@onlyworlds/sdk 4.112.0 → 4.114.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.
@@ -0,0 +1,364 @@
1
+ /*
2
+ * The Waymark's fan-out (@onlyworlds/sdk/waymark.css). Bundle it with the page that mounts
3
+ * @onlyworlds/sdk/waymark: the component sets no inline style, so this file is all of its look.
4
+ *
5
+ * Every colour is a value of the Waymark's states file (waymark-states: two grounds, dark and paper),
6
+ * declared once below under its ground and its key; the rules read them only through the ground's
7
+ * names. The mark: in its ink on the ground at rest, no tile; the hover tile behind it on hover; an
8
+ * outline of 2px in the ink, offset 2px, on focus; the open tile behind it while the fan-out is open.
9
+ */
10
+
11
+ .ow-waymark {
12
+ --ow-waymark-dark-page: #02050a;
13
+ --ow-waymark-dark-bg: #0b0f14;
14
+ --ow-waymark-dark-popover: #111823;
15
+ --ow-waymark-dark-ink: #37c1f0;
16
+ --ow-waymark-dark-text: #e2e8f0;
17
+ --ow-waymark-dark-muted: #94a3b8;
18
+ --ow-waymark-dark-line: #243040;
19
+ --ow-waymark-dark-hover-tile: #0f212a;
20
+ --ow-waymark-dark-open-tile: #153644;
21
+
22
+ --ow-waymark-paper-page: #ebe8df;
23
+ --ow-waymark-paper-bg: #f6f4ee;
24
+ --ow-waymark-paper-popover: #ffffff;
25
+ --ow-waymark-paper-ink: #1b2430;
26
+ --ow-waymark-paper-text: #1b2430;
27
+ --ow-waymark-paper-muted: #5b6573;
28
+ --ow-waymark-paper-line: #d5d1c4;
29
+ --ow-waymark-paper-hover-tile: #e7e5e1;
30
+ --ow-waymark-paper-open-tile: #d3d3d0;
31
+
32
+ position: relative;
33
+ display: inline-block;
34
+ vertical-align: middle;
35
+ line-height: 1;
36
+ }
37
+
38
+ .ow-waymark--dark {
39
+ --ow-waymark-page: var(--ow-waymark-dark-page);
40
+ --ow-waymark-popover: var(--ow-waymark-dark-popover);
41
+ --ow-waymark-ink: var(--ow-waymark-dark-ink);
42
+ --ow-waymark-text: var(--ow-waymark-dark-text);
43
+ --ow-waymark-muted: var(--ow-waymark-dark-muted);
44
+ --ow-waymark-line: var(--ow-waymark-dark-line);
45
+ --ow-waymark-hover-tile: var(--ow-waymark-dark-hover-tile);
46
+ --ow-waymark-open-tile: var(--ow-waymark-dark-open-tile);
47
+ --ow-waymark-shadow: var(--ow-waymark-dark-page);
48
+ }
49
+
50
+ .ow-waymark--paper {
51
+ --ow-waymark-page: var(--ow-waymark-paper-page);
52
+ --ow-waymark-popover: var(--ow-waymark-paper-popover);
53
+ --ow-waymark-ink: var(--ow-waymark-paper-ink);
54
+ --ow-waymark-text: var(--ow-waymark-paper-text);
55
+ --ow-waymark-muted: var(--ow-waymark-paper-muted);
56
+ --ow-waymark-line: var(--ow-waymark-paper-line);
57
+ --ow-waymark-hover-tile: var(--ow-waymark-paper-hover-tile);
58
+ --ow-waymark-open-tile: var(--ow-waymark-paper-open-tile);
59
+ --ow-waymark-shadow: var(--ow-waymark-paper-line);
60
+ }
61
+
62
+ .ow-waymark [hidden] {
63
+ display: none !important;
64
+ }
65
+
66
+ /* The mark: a button, the glyph alone. */
67
+ .ow-waymark__mark {
68
+ appearance: none;
69
+ display: inline-flex;
70
+ margin: 0 0 0 0.3em;
71
+ padding: 0.15em;
72
+ border: 0;
73
+ border-radius: 6px;
74
+ background: none;
75
+ color: var(--ow-waymark-ink);
76
+ font: inherit;
77
+ cursor: pointer;
78
+ vertical-align: middle;
79
+ position: relative;
80
+ }
81
+ /* The tap area: at least 44 by 44 px around the glyph at every width, drawn by nothing and taking no
82
+ room, so the glyph and the name line stay where they are. */
83
+ .ow-waymark__mark::before {
84
+ content: '';
85
+ position: absolute;
86
+ top: 50%;
87
+ left: 50%;
88
+ width: max(44px, 100%);
89
+ height: max(44px, 100%);
90
+ transform: translate(-50%, -50%);
91
+ }
92
+ .ow-waymark__mark .ow-waymark__glyph {
93
+ display: block;
94
+ width: 1em;
95
+ height: 1em;
96
+ }
97
+ .ow-waymark__mark:hover {
98
+ background: var(--ow-waymark-hover-tile);
99
+ }
100
+ .ow-waymark__mark:focus {
101
+ outline: none;
102
+ }
103
+ .ow-waymark__mark:focus-visible {
104
+ outline: 2px solid var(--ow-waymark-ink);
105
+ outline-offset: 2px;
106
+ }
107
+ .ow-waymark__mark[aria-expanded='true'] {
108
+ background: var(--ow-waymark-open-tile);
109
+ }
110
+
111
+ /* The fan-out: a popover under the name. */
112
+ .ow-waymark__pop {
113
+ position: absolute;
114
+ top: calc(100% + 6px);
115
+ left: 0;
116
+ z-index: 1000;
117
+ box-sizing: border-box;
118
+ width: 300px;
119
+ max-width: calc(100vw - 16px);
120
+ padding: 12px 12px 8px;
121
+ border: 1px solid var(--ow-waymark-line);
122
+ border-radius: 12px;
123
+ background: var(--ow-waymark-popover);
124
+ box-shadow: 0 8px 24px var(--ow-waymark-shadow);
125
+ color: var(--ow-waymark-text);
126
+ font: 400 13px/1.45 system-ui, 'Segoe UI', sans-serif;
127
+ letter-spacing: normal;
128
+ text-align: left;
129
+ text-transform: none;
130
+ white-space: normal;
131
+ }
132
+ .ow-waymark__grab {
133
+ display: none;
134
+ }
135
+ .ow-waymark__scrim {
136
+ display: none;
137
+ }
138
+
139
+ /* 1. The name line. */
140
+ .ow-waymark__head {
141
+ display: flex;
142
+ gap: 11px;
143
+ align-items: center;
144
+ padding: 2px 2px 6px;
145
+ }
146
+ .ow-waymark__tile {
147
+ display: inline-flex;
148
+ flex: none;
149
+ padding: 5px;
150
+ border-radius: 6px;
151
+ background: var(--ow-waymark-open-tile);
152
+ color: var(--ow-waymark-ink);
153
+ }
154
+ .ow-waymark__tile .ow-waymark__glyph {
155
+ display: block;
156
+ width: 22px;
157
+ height: 22px;
158
+ }
159
+ .ow-waymark__names {
160
+ min-width: 0;
161
+ }
162
+ .ow-waymark__name {
163
+ font-size: 15px;
164
+ font-weight: 700;
165
+ overflow-wrap: anywhere;
166
+ }
167
+ .ow-waymark__sub {
168
+ display: flex;
169
+ flex-wrap: wrap;
170
+ gap: 6px;
171
+ color: var(--ow-waymark-muted);
172
+ font-size: 12px;
173
+ }
174
+ .ow-waymark__door {
175
+ margin-bottom: 2px;
176
+ padding: 2px 4px 8px;
177
+ border-bottom: 1px solid var(--ow-waymark-line);
178
+ color: var(--ow-waymark-muted);
179
+ font-size: 12px;
180
+ }
181
+
182
+ /* 2 to 4. The menu. */
183
+ .ow-waymark__sec {
184
+ padding: 8px 4px 3px;
185
+ color: var(--ow-waymark-muted);
186
+ font-size: 11.5px;
187
+ }
188
+ .ow-waymark__sep {
189
+ margin: 6px 0 2px;
190
+ border-top: 1px solid var(--ow-waymark-line);
191
+ }
192
+ .ow-waymark__row {
193
+ appearance: none;
194
+ display: flex;
195
+ gap: 10px;
196
+ align-items: center;
197
+ box-sizing: border-box;
198
+ width: 100%;
199
+ min-height: 32px;
200
+ margin: 0;
201
+ padding: 6px 4px;
202
+ border: 0;
203
+ border-radius: 6px;
204
+ background: none;
205
+ color: var(--ow-waymark-text);
206
+ font: inherit;
207
+ font-weight: 400;
208
+ text-align: left;
209
+ text-decoration: none;
210
+ cursor: pointer;
211
+ }
212
+ .ow-waymark__row:hover {
213
+ background: var(--ow-waymark-hover-tile);
214
+ }
215
+ .ow-waymark__row:focus {
216
+ outline: none;
217
+ }
218
+ .ow-waymark__row:focus-visible {
219
+ outline: 2px solid var(--ow-waymark-ink);
220
+ outline-offset: -2px;
221
+ }
222
+ .ow-waymark__icon {
223
+ flex: none;
224
+ width: 18px;
225
+ height: 18px;
226
+ }
227
+ .ow-waymark__icon--small {
228
+ width: 16px;
229
+ height: 16px;
230
+ }
231
+ .ow-waymark__label {
232
+ min-width: 0;
233
+ }
234
+ .ow-waymark__state {
235
+ margin-left: auto;
236
+ padding-left: 8px;
237
+ color: var(--ow-waymark-muted);
238
+ font-size: 11.5px;
239
+ text-align: right;
240
+ }
241
+ .ow-waymark__chevron {
242
+ flex: none;
243
+ width: 16px;
244
+ height: 16px;
245
+ }
246
+ .ow-waymark__state:empty + .ow-waymark__chevron {
247
+ margin-left: auto;
248
+ }
249
+ .ow-waymark__row[aria-expanded='true'] .ow-waymark__chevron {
250
+ transform: rotate(180deg);
251
+ }
252
+ /* Grey says the row cannot open now, and nothing else. */
253
+ .ow-waymark__row--cannot .ow-waymark__label,
254
+ .ow-waymark__row--cannot .ow-waymark__icon {
255
+ color: var(--ow-waymark-muted);
256
+ }
257
+ .ow-waymark__row--lens {
258
+ padding-left: 30px;
259
+ }
260
+ .ow-waymark__row--lens[aria-checked='true'] {
261
+ background: var(--ow-waymark-open-tile);
262
+ }
263
+
264
+ /* The copied toast. */
265
+ .ow-waymark__toast {
266
+ position: absolute;
267
+ top: calc(100% + 6px);
268
+ left: 0;
269
+ z-index: 1001;
270
+ display: inline-flex;
271
+ flex-direction: column;
272
+ gap: 8px;
273
+ align-items: flex-start;
274
+ padding: 9px 14px;
275
+ border: 1px solid var(--ow-waymark-line);
276
+ border-radius: 9px;
277
+ background: var(--ow-waymark-popover);
278
+ box-shadow: 0 6px 18px var(--ow-waymark-shadow);
279
+ color: var(--ow-waymark-text);
280
+ font: 400 13px/1.45 system-ui, 'Segoe UI', sans-serif;
281
+ white-space: nowrap;
282
+ }
283
+ .ow-waymark__toast-line {
284
+ display: inline-flex;
285
+ gap: 8px;
286
+ align-items: center;
287
+ }
288
+ /* While the fan-out is open (a failed copy), the toast sits above the name, clear of it. */
289
+ .ow-waymark__pop:not([hidden]) ~ .ow-waymark__toast {
290
+ top: auto;
291
+ bottom: calc(100% + 6px);
292
+ }
293
+ /* The address after a failed copy: read-only, selected whole by one click. */
294
+ .ow-waymark__address {
295
+ box-sizing: border-box;
296
+ width: min(340px, calc(100vw - 48px));
297
+ margin: 0;
298
+ padding: 6px 8px;
299
+ border: 1px solid var(--ow-waymark-line);
300
+ border-radius: 6px;
301
+ background: var(--ow-waymark-popover);
302
+ color: var(--ow-waymark-text);
303
+ font: 400 12px/1.4 ui-monospace, 'Cascadia Mono', Consolas, monospace;
304
+ user-select: all;
305
+ }
306
+ .ow-waymark__address:focus-visible {
307
+ outline: 2px solid var(--ow-waymark-ink);
308
+ outline-offset: 1px;
309
+ }
310
+
311
+ /* 390 px wide and below: a sheet from the bottom, the page behind dimmed, rows tall enough to touch. */
312
+ @media (max-width: 390px) {
313
+ .ow-waymark__scrim {
314
+ display: block;
315
+ position: fixed;
316
+ inset: 0;
317
+ z-index: 999;
318
+ background: var(--ow-waymark-page);
319
+ opacity: 0.6;
320
+ }
321
+ .ow-waymark__pop {
322
+ position: fixed;
323
+ top: auto;
324
+ right: 0;
325
+ bottom: 0;
326
+ left: 0;
327
+ width: auto;
328
+ max-width: none;
329
+ max-height: 85vh;
330
+ overflow-y: auto;
331
+ padding: 8px 14px 18px;
332
+ border-width: 1px 0 0;
333
+ border-radius: 18px 18px 0 0;
334
+ box-shadow: none;
335
+ }
336
+ .ow-waymark__grab {
337
+ display: block;
338
+ width: 40px;
339
+ height: 4px;
340
+ margin: 0 auto 8px;
341
+ border-radius: 2px;
342
+ background: var(--ow-waymark-line);
343
+ }
344
+ /* Rows at least 44 px tall to touch: more padding, the same type. */
345
+ .ow-waymark__row {
346
+ min-height: 44px;
347
+ padding: 12px 6px;
348
+ font-size: 15px;
349
+ }
350
+ .ow-waymark__row--lens {
351
+ padding-left: 30px;
352
+ }
353
+ .ow-waymark__toast {
354
+ position: fixed;
355
+ top: auto;
356
+ bottom: 24px;
357
+ left: 50%;
358
+ transform: translateX(-50%);
359
+ }
360
+ .ow-waymark__pop:not([hidden]) ~ .ow-waymark__toast {
361
+ top: 16px;
362
+ bottom: auto;
363
+ }
364
+ }
@@ -0,0 +1,100 @@
1
+ /** What a person must have before a tool's link works: signed in to the tool (`account`), or the world already in the tool on this device (`device`). */
2
+ type OwToolNeeds = 'account' | 'device';
3
+ /** A tool's `open` in the tools list: its link templates and what they need first. */
4
+ interface OwToolOpen {
5
+ /** The link that opens a world, holding `{world}` (the world's id); null without one. */
6
+ world: string | null;
7
+ /** The link that opens one element, holding `{id}` and, if it needs them, `{world}` and `{type}` (the type word); null without one. */
8
+ element: string | null;
9
+ /** What the person needs first; null for nothing, which is the one kind of row a public page offers. */
10
+ needs: OwToolNeeds | null;
11
+ }
12
+ /** The keys of one tools list row that `openersFor` reads; a row straight from `tools.json` carries more, and they are ignored. */
13
+ interface OwTool {
14
+ /** The list's id for the tool, the row's `id` in the menu. */
15
+ id: string;
16
+ name: string;
17
+ url: string;
18
+ /** The tool's client name (`X-OW-Client`), which a surface names itself by; null without one. */
19
+ client: string | null;
20
+ /** `listed` rows are offered; `built` and `delisted` rows never are. */
21
+ rung: 'built' | 'listed' | 'delisted';
22
+ /** How a link opens a world or an element in the tool; null: never offered. */
23
+ open: OwToolOpen | null;
24
+ }
25
+
26
+ /** Who reads the fan-out: a member of the world, a guest (a seat in it, a member too), or the public (signed out). */
27
+ type OwWaymarkReader = 'member' | 'guest' | 'public';
28
+ /** How a person reaches the fan-out: `mark`, the OnlyWorlds mark beside the name, a button; `menu`, an "Open with" entry the surface puts in its own "..." menu, and no mark; `both`, the mark and the entry. */
29
+ type OwWaymarkEntry = 'mark' | 'menu' | 'both';
30
+ /** One lens the reader may read the element through: its id (an element id, as the address takes it) and its name. */
31
+ interface OwWaymarkLens {
32
+ id: string;
33
+ name: string;
34
+ }
35
+ /** What `mountWaymark` takes. Only `world` and `reader` are required. */
36
+ interface OwWaymarkOptions {
37
+ /** The world: its id and name, as `GET /world` or a folder's `world.json` gives them (its `x_names`, when there, words the type). */
38
+ world: {
39
+ id: string;
40
+ name: string;
41
+ [k: string]: unknown;
42
+ };
43
+ /** The element, as the API serves it (`id`, `type`, `name`; a member's body carries `doors`); absent, the fan-out is the world's own. */
44
+ element?: {
45
+ id: string;
46
+ type: string;
47
+ name: string;
48
+ [k: string]: unknown;
49
+ } | null;
50
+ /** `member`, `guest` or `public`. The public face shows the name line without the last door, the rows that need nothing first, and Copy link. */
51
+ reader: OwWaymarkReader;
52
+ /** The client name of the surface's own tool; its row says "You are here". */
53
+ tool?: string | null;
54
+ /** Whether the reader is signed in; null when the surface cannot know, and then no row says so. */
55
+ signedIn?: boolean | null;
56
+ /** False in a desktop app, which cannot see the browser's sign-in. Default true. */
57
+ browser?: boolean;
58
+ /** True on a phone. Default false. */
59
+ phone?: boolean;
60
+ /** The tools list's rows. Default `TOOLS`, the list baked into this release. */
61
+ tools?: readonly OwTool[];
62
+ /** The lenses the surface offers, for the Through row; absent or empty, no Through row. Never shown to the public. */
63
+ lenses?: readonly OwWaymarkLens[] | null;
64
+ /** The ground the fan-out sits on: `dark` (the brand cyan mark) or `paper` (the mark in a dark ink). Default `dark`. */
65
+ ground?: 'dark' | 'paper';
66
+ /** The way in: `mark`, `menu` or `both`. Default `mark`. */
67
+ entry?: OwWaymarkEntry;
68
+ /** With `menu` or `both`: the surface's own visible element (its "..." button) that takes focus when the fan-out, opened from the entry, closes by Escape; absent, the entry takes it. Refused with `mark`. */
69
+ returnFocus?: HTMLElement | null;
70
+ }
71
+ /** The disposer `mountWaymark` returns: call it to remove every node, listener and timer the fan-out added. */
72
+ interface OwWaymark {
73
+ (): void;
74
+ /** With `entry: 'menu'` or `'both'`, the "Open with" button for the surface to put in its own "..." menu (it opens the fan-out); with `mark`, null. */
75
+ readonly entry: HTMLButtonElement | null;
76
+ }
77
+ /**
78
+ * Draw the Waymark into `target`, the element that holds a world's or an element's name: the OnlyWorlds
79
+ * mark at its end (`entry: 'mark'`), or nothing visible there and an "Open with" entry for the surface's
80
+ * own menu (`entry: 'menu'`), or both (`entry: 'both'`), each opening the same fan-out: the name line
81
+ * (and, for a member or guest, "Last shaped in Atlas, 12 Oct" from `doorsOf` and `doorWhere`), the Open
82
+ * with rows `openersFor` gives, each with its word, the Through row when the surface offers lenses, and
83
+ * Copy link last, which copies the site's address with the world's id (`elementAddress`) and says "Link
84
+ * copied" and closes; with no clipboard, or the copy refused, the fan-out stays open and the toast says
85
+ * "Could not copy the link." over the address, selected in a read-only line to copy by hand, until the
86
+ * fan-out closes. Focus moving out of the fan-out closes it and stays where it was moved.
87
+ *
88
+ * Keyboard: the mark is a button and the fan-out a menu; Tab goes from the mark through the rows in
89
+ * order, the arrow keys, Home and End move within it, Escape closes it and returns focus to what opened
90
+ * it: the mark, or for the entry `returnFocus` when given (the surface's "..." button, which stays
91
+ * visible when its menu closes), else the entry. A click outside closes it. At 390 px wide and below the stylesheet draws it as a sheet
92
+ * from the bottom. The page must load `@onlyworlds/sdk/waymark.css`; no node carries a style attribute.
93
+ *
94
+ * Refuses, before anything is drawn, an unknown option key by name and a value of the wrong kind (a
95
+ * TypeError), and an address `elementAddress` refuses (an `OwAddressError`: a world id that is not an
96
+ * id, an unknown type, an element or lens id that is not a UUID). Returns the disposer.
97
+ */
98
+ declare function mountWaymark(target: Element, options: OwWaymarkOptions): OwWaymark;
99
+
100
+ export { type OwWaymark, type OwWaymarkEntry, type OwWaymarkLens, type OwWaymarkOptions, type OwWaymarkReader, mountWaymark };