@jupyterlab/ui-components 4.0.0-alpha.33 → 4.0.0-alpha.35

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 (49) hide show
  1. package/lib/components/form.d.ts +17 -2
  2. package/lib/components/form.js +52 -11
  3. package/lib/components/form.js.map +1 -1
  4. package/lib/components/vdom.d.ts +1 -1
  5. package/lib/components/windowedlist.d.ts +1 -1
  6. package/lib/components/windowedlist.js +2 -1
  7. package/lib/components/windowedlist.js.map +1 -1
  8. package/lib/hoverbox.d.ts +1 -1
  9. package/lib/icon/labicon.js +49 -48
  10. package/lib/icon/labicon.js.map +1 -1
  11. package/lib/icon/widgets/tabbarsvg.js +2 -1
  12. package/lib/icon/widgets/tabbarsvg.js.map +1 -1
  13. package/lib/tokens.d.ts +1 -1
  14. package/package.json +22 -20
  15. package/src/FormRendererRegistry.tsx +60 -0
  16. package/src/components/accordiontoolbar.ts +252 -0
  17. package/src/components/button.tsx +45 -0
  18. package/src/components/collapser.ts +176 -0
  19. package/src/components/form.tsx +678 -0
  20. package/src/components/htmlselect.tsx +99 -0
  21. package/src/components/iframe.ts +153 -0
  22. package/src/components/index.ts +20 -0
  23. package/src/components/inputgroup.tsx +51 -0
  24. package/src/components/interface.ts +9 -0
  25. package/src/components/menu.ts +442 -0
  26. package/src/components/panelwithtoolbar.ts +41 -0
  27. package/src/components/search.tsx +216 -0
  28. package/src/components/sidepanel.ts +168 -0
  29. package/src/components/spinner.ts +31 -0
  30. package/src/components/styling.ts +114 -0
  31. package/src/components/switch.ts +103 -0
  32. package/src/components/toolbar.tsx +1119 -0
  33. package/src/components/vdom.ts +324 -0
  34. package/src/components/windowedlist.ts +1422 -0
  35. package/src/hoverbox.ts +401 -0
  36. package/src/icon/iconimports.ts +206 -0
  37. package/src/icon/index.ts +6 -0
  38. package/src/icon/labicon.tsx +955 -0
  39. package/src/icon/widgets/commandpalettesvg.ts +78 -0
  40. package/src/icon/widgets/index.ts +6 -0
  41. package/src/icon/widgets/menusvg.ts +218 -0
  42. package/src/icon/widgets/tabbarsvg.ts +122 -0
  43. package/src/index.ts +13 -0
  44. package/src/style/icon.ts +581 -0
  45. package/src/style/index.ts +4 -0
  46. package/src/svg.d.ts +58 -0
  47. package/src/tokens.ts +68 -0
  48. package/src/utils.ts +90 -0
  49. package/style/rjsfTemplates.css +0 -4
@@ -0,0 +1,955 @@
1
+ // Copyright (c) Jupyter Development Team.
2
+ // Distributed under the terms of the Modified BSD License.
3
+
4
+ import { IRenderMime } from '@jupyterlab/rendermime-interfaces';
5
+ import { UUID } from '@lumino/coreutils';
6
+ import { Signal } from '@lumino/signaling';
7
+ import { ElementAttrs, VirtualElement, VirtualNode } from '@lumino/virtualdom';
8
+ import React from 'react';
9
+ import { createRoot, Root } from 'react-dom/client';
10
+ import badSvgstr from '../../style/debug/bad.svg';
11
+ import blankSvgstr from '../../style/debug/blank.svg';
12
+ import refreshSvgstr from '../../style/icons/toolbar/refresh.svg';
13
+ import { LabIconStyle } from '../style';
14
+ import { classes, getReactAttrs } from '../utils';
15
+
16
+ export class LabIcon implements LabIcon.ILabIcon, VirtualElement.IRenderer {
17
+ /** *********
18
+ * statics *
19
+ ***********/
20
+
21
+ /**
22
+ * Remove any rendered icon from the element that contains it
23
+ *
24
+ * @param container - a DOM node into which an icon was
25
+ * previously rendered
26
+ *
27
+ * @returns the cleaned container
28
+ */
29
+ static remove(container: HTMLElement): HTMLElement {
30
+ // clean up all children
31
+ while (container.firstChild) {
32
+ container.firstChild.remove();
33
+ }
34
+
35
+ // remove all classes
36
+ container.className = '';
37
+
38
+ return container;
39
+ }
40
+
41
+ /**
42
+ * Resolve an icon name or a {name, svgstr} pair into an
43
+ * actual LabIcon.
44
+ *
45
+ * @param icon - either a string with the name of an existing icon
46
+ * or an object with {name: string, svgstr: string} fields.
47
+ *
48
+ * @returns a LabIcon instance
49
+ */
50
+ static resolve({ icon }: { icon: LabIcon.IResolvable }): LabIcon {
51
+ if (icon instanceof LabIcon) {
52
+ // icon already is a LabIcon; nothing to do here
53
+ return icon;
54
+ }
55
+
56
+ if (typeof icon === 'string') {
57
+ // do a dynamic lookup of existing icon by name
58
+ const resolved = LabIcon._instances.get(icon);
59
+ if (resolved) {
60
+ return resolved;
61
+ }
62
+
63
+ // lookup failed
64
+ if (LabIcon._debug) {
65
+ // fail noisily
66
+ console.warn(
67
+ `Lookup failed for icon, creating loading icon. icon: ${icon}`
68
+ );
69
+ }
70
+
71
+ // no matching icon currently registered, create a new loading icon
72
+ // TODO: find better icon (maybe animate?) for loading icon
73
+ return new LabIcon({ name: icon, svgstr: refreshSvgstr, _loading: true });
74
+ }
75
+
76
+ // icon was provided as a non-LabIcon {name, svgstr} pair, communicating
77
+ // an intention to create a new icon
78
+ return new LabIcon(icon);
79
+ }
80
+
81
+ /**
82
+ * Resolve an icon name or a {name, svgstr} pair into a DOM element.
83
+ * If icon arg is undefined, the function will fall back to trying to render
84
+ * the icon as a CSS background image, via the iconClass arg.
85
+ * If both icon and iconClass are undefined, this function will return
86
+ * an empty div.
87
+ *
88
+ * @param icon - optional, either a string with the name of an existing icon
89
+ * or an object with {name: string, svgstr: string} fields
90
+ *
91
+ * @param iconClass - optional, if the icon arg is not set, the iconClass arg
92
+ * should be a CSS class associated with an existing CSS background-image
93
+ *
94
+ * @param fallback - DEPRECATED, optional, a LabIcon instance that will
95
+ * be used if neither icon nor iconClass are defined
96
+ *
97
+ * @param props - any additional args are passed though to the element method
98
+ * of the resolved icon on render
99
+ *
100
+ * @returns a DOM node with the resolved icon rendered into it
101
+ */
102
+ static resolveElement({
103
+ icon,
104
+ iconClass,
105
+ fallback,
106
+ ...props
107
+ }: Partial<LabIcon.IResolverProps> & LabIcon.IProps): HTMLElement {
108
+ if (!Private.isResolvable(icon)) {
109
+ if (!iconClass && fallback) {
110
+ // if neither icon nor iconClass are defined/resolvable, use fallback
111
+ return fallback.element(props);
112
+ }
113
+
114
+ // set the icon's class to iconClass plus props.className
115
+ props.className = classes(iconClass, props.className);
116
+ // render icon as css background image, assuming one is set on iconClass
117
+ return Private.blankElement(props);
118
+ }
119
+
120
+ return LabIcon.resolve({ icon }).element(props);
121
+ }
122
+
123
+ /**
124
+ * Resolve an icon name or a {name, svgstr} pair into a React component.
125
+ * If icon arg is undefined, the function will fall back to trying to render
126
+ * the icon as a CSS background image, via the iconClass arg.
127
+ * If both icon and iconClass are undefined, the returned component
128
+ * will simply render an empty div.
129
+ *
130
+ * @param icon - optional, either a string with the name of an existing icon
131
+ * or an object with {name: string, svgstr: string} fields
132
+ *
133
+ * @param iconClass - optional, if the icon arg is not set, the iconClass arg
134
+ * should be a CSS class associated with an existing CSS background-image
135
+ *
136
+ * @param fallback - DEPRECATED, optional, a LabIcon instance that will
137
+ * be used if neither icon nor iconClass are defined
138
+ *
139
+ * @param props - any additional args are passed though to the React component
140
+ * of the resolved icon on render
141
+ *
142
+ * @returns a React component that will render the resolved icon
143
+ */
144
+ static resolveReact({
145
+ icon,
146
+ iconClass,
147
+ fallback,
148
+ ...props
149
+ }: Partial<LabIcon.IResolverProps> & LabIcon.IReactProps): JSX.Element {
150
+ if (!Private.isResolvable(icon)) {
151
+ if (!iconClass && fallback) {
152
+ // if neither icon nor iconClass are defined/resolvable, use fallback
153
+ return <fallback.react {...props} />;
154
+ }
155
+
156
+ // set the icon's class to iconClass plus props.className
157
+ props.className = classes(iconClass, props.className);
158
+ // render icon as css background image, assuming one is set on iconClass
159
+ return <Private.blankReact {...props} />;
160
+ }
161
+
162
+ const resolved = LabIcon.resolve({ icon });
163
+ return <resolved.react {...props} />;
164
+ }
165
+
166
+ /**
167
+ * Resolve a {name, svgstr} pair into an actual svg node.
168
+ */
169
+ static resolveSvg({ name, svgstr }: LabIcon.IIcon): HTMLElement | null {
170
+ const svgDoc = new DOMParser().parseFromString(
171
+ Private.svgstrShim(svgstr),
172
+ 'image/svg+xml'
173
+ );
174
+
175
+ const svgError = svgDoc.querySelector('parsererror');
176
+
177
+ // structure of error element varies by browser, search at top level
178
+ if (svgError) {
179
+ // parse failed, svgElement will be an error box
180
+ const errmsg = `SVG HTML was malformed for LabIcon instance.\nname: ${name}, svgstr: ${svgstr}`;
181
+ if (LabIcon._debug) {
182
+ // fail noisily, render the error box
183
+ console.error(errmsg);
184
+ return svgError as HTMLElement;
185
+ } else {
186
+ // bad svg is always a real error, fail silently but warn
187
+ console.warn(errmsg);
188
+ return null;
189
+ }
190
+ } else {
191
+ // parse succeeded
192
+ return svgDoc.documentElement;
193
+ }
194
+ }
195
+
196
+ /**
197
+ * Toggle icon debug from off-to-on, or vice-versa.
198
+ *
199
+ * @param debug - optional boolean to force debug on or off
200
+ */
201
+ static toggleDebug(debug?: boolean): void {
202
+ LabIcon._debug = debug ?? !LabIcon._debug;
203
+ }
204
+
205
+ private static _debug: boolean = false;
206
+ private static _instances = new Map<string, LabIcon>();
207
+
208
+ /** *********
209
+ * members *
210
+ ***********/
211
+
212
+ constructor({
213
+ name,
214
+ svgstr,
215
+ render,
216
+ unrender,
217
+ _loading = false
218
+ }: LabIcon.IOptions & { _loading?: boolean }) {
219
+ if (!(name && svgstr)) {
220
+ // sanity check failed
221
+ console.error(
222
+ `When defining a new LabIcon, name and svgstr must both be non-empty strings. name: ${name}, svgstr: ${svgstr}`
223
+ );
224
+ return badIcon;
225
+ }
226
+
227
+ // currently this needs to be set early, before checks for existing icons
228
+ this._loading = _loading;
229
+
230
+ // check to see if this is a redefinition of an existing icon
231
+ if (LabIcon._instances.has(name)) {
232
+ // fetch the existing icon, replace its svg, then return it
233
+ const icon = LabIcon._instances.get(name)!;
234
+ if (this._loading) {
235
+ // replace the placeholder svg in icon
236
+ icon.svgstr = svgstr;
237
+ this._loading = false;
238
+ return icon;
239
+ } else {
240
+ // already loaded icon svg exists; replace it and warn
241
+ if (LabIcon._debug) {
242
+ console.warn(
243
+ `Redefining previously loaded icon svgstr. name: ${name}, svgstrOld: ${icon.svgstr}, svgstr: ${svgstr}`
244
+ );
245
+ }
246
+ icon.svgstr = svgstr;
247
+ return icon;
248
+ }
249
+ }
250
+
251
+ this.name = name;
252
+ this.react = this._initReact(name);
253
+ this.svgstr = svgstr;
254
+
255
+ // setup custom render/unrender methods, if passed in
256
+ this._initRender({ render, unrender });
257
+
258
+ LabIcon._instances.set(this.name, this);
259
+ }
260
+
261
+ /**
262
+ * Get a view of this icon that is bound to the specified icon/style props
263
+ *
264
+ * @param optional icon/style props (same as args for .element
265
+ * and .react methods). These will be bound to the resulting view
266
+ *
267
+ * @returns a view of this LabIcon instance
268
+ */
269
+ bindprops(props?: LabIcon.IProps): LabIcon {
270
+ const view = Object.create(this);
271
+ view._props = props;
272
+ view.react = view._initReact(view.name + '_bind');
273
+ return view;
274
+ }
275
+
276
+ /**
277
+ * Create an icon as a DOM element
278
+ *
279
+ * @param className - a string that will be used as the class
280
+ * of the container element. Overrides any existing class
281
+ *
282
+ * @param container - a preexisting DOM element that
283
+ * will be used as the container for the svg element
284
+ *
285
+ * @param label - text that will be displayed adjacent
286
+ * to the icon
287
+ *
288
+ * @param title - a tooltip for the icon
289
+ *
290
+ * @param tag - if container is not explicitly
291
+ * provided, this tag will be used when creating the container
292
+ *
293
+ * @param stylesheet - optional string naming a builtin icon
294
+ * stylesheet, for example 'menuItem' or `statusBar`. Can also be an
295
+ * object defining a custom icon stylesheet, or a list of builtin
296
+ * stylesheet names and/or custom stylesheet objects. If array,
297
+ * the given stylesheets will be merged.
298
+ *
299
+ * See @jupyterlab/ui-components/src/style/icon.ts for details
300
+ *
301
+ * @param elementPosition - optional position for the inner svg element
302
+ *
303
+ * @param elementSize - optional size for the inner svg element.
304
+ * Set to 'normal' to get a standard 16px x 16px icon
305
+ *
306
+ * @param ...elementCSS - all additional args are treated as
307
+ * overrides for the CSS props applied to the inner svg element
308
+ *
309
+ * @returns A DOM element that contains an (inline) svg element
310
+ * that displays an icon
311
+ */
312
+ element(props: LabIcon.IProps = {}): HTMLElement {
313
+ let {
314
+ className,
315
+ container,
316
+ label,
317
+ title,
318
+ tag = 'div',
319
+ ...styleProps
320
+ }: LabIcon.IProps = { ...this._props, ...props };
321
+
322
+ // check if icon element is already set
323
+ const maybeSvgElement = container?.firstChild as HTMLElement;
324
+ if (maybeSvgElement?.dataset?.iconId === this._uuid) {
325
+ // return the existing icon element
326
+ return maybeSvgElement;
327
+ }
328
+
329
+ // ensure that svg html is valid
330
+ if (!this.svgElement) {
331
+ // bail if failing silently, return blank element
332
+ return document.createElement('div');
333
+ }
334
+
335
+ let returnSvgElement = true;
336
+ if (container) {
337
+ // take ownership by removing any existing children
338
+ while (container.firstChild) {
339
+ container.firstChild.remove();
340
+ }
341
+ } else {
342
+ // create a container if needed
343
+ container = document.createElement(tag);
344
+
345
+ returnSvgElement = false;
346
+ }
347
+ if (label != null) {
348
+ container.textContent = label;
349
+ }
350
+ Private.initContainer({ container, className, styleProps, title });
351
+
352
+ // add the svg node to the container
353
+ const svgElement = this.svgElement.cloneNode(true) as HTMLElement;
354
+ container.appendChild(svgElement);
355
+
356
+ return returnSvgElement ? svgElement : container;
357
+ }
358
+
359
+ render(container: HTMLElement, options?: LabIcon.IRendererOptions): void {
360
+ let label = options?.children?.[0];
361
+ // narrow type of label
362
+ if (typeof label !== 'string') {
363
+ label = undefined;
364
+ }
365
+
366
+ this.element({
367
+ container,
368
+ label,
369
+ ...options?.props
370
+ });
371
+ }
372
+
373
+ protected get svgElement(): HTMLElement | null {
374
+ if (this._svgElement === undefined) {
375
+ this._svgElement = this._initSvg({ uuid: this._uuid });
376
+ }
377
+
378
+ return this._svgElement;
379
+ }
380
+
381
+ protected get svgInnerHTML(): string | null {
382
+ if (this._svgInnerHTML === undefined) {
383
+ if (this.svgElement === null) {
384
+ // the svg element resolved to null, mark this null too
385
+ this._svgInnerHTML = null;
386
+ } else {
387
+ this._svgInnerHTML = this.svgElement.innerHTML;
388
+ }
389
+ }
390
+
391
+ return this._svgInnerHTML;
392
+ }
393
+
394
+ protected get svgReactAttrs(): any | null {
395
+ if (this._svgReactAttrs === undefined) {
396
+ if (this.svgElement === null) {
397
+ // the svg element resolved to null, mark this null too
398
+ this._svgReactAttrs = null;
399
+ } else {
400
+ this._svgReactAttrs = getReactAttrs(this.svgElement, {
401
+ ignore: ['data-icon-id']
402
+ });
403
+ }
404
+ }
405
+
406
+ return this._svgReactAttrs;
407
+ }
408
+
409
+ get svgstr(): string {
410
+ return this._svgstr;
411
+ }
412
+
413
+ set svgstr(svgstr: string) {
414
+ this._svgstr = svgstr;
415
+
416
+ // associate a new unique id with this particular svgstr
417
+ const uuid = UUID.uuid4();
418
+ const uuidOld = this._uuid;
419
+ this._uuid = uuid;
420
+
421
+ // empty the svg parsing intermediates cache
422
+ this._svgElement = undefined;
423
+ this._svgInnerHTML = undefined;
424
+ this._svgReactAttrs = undefined;
425
+
426
+ // update icon elements created using .element method
427
+ document
428
+ .querySelectorAll(`[data-icon-id="${uuidOld}"]`)
429
+ .forEach(oldSvgElement => {
430
+ if (this.svgElement) {
431
+ oldSvgElement.replaceWith(this.svgElement.cloneNode(true));
432
+ }
433
+ });
434
+
435
+ // trigger update of icon elements created using other methods
436
+ this._svgReplaced.emit();
437
+ }
438
+
439
+ unrender?(container: HTMLElement, options?: LabIcon.IRendererOptions): void;
440
+
441
+ protected _initReact(displayName: string) {
442
+ const component = React.forwardRef(
443
+ (props: LabIcon.IProps = {}, ref: LabIcon.IReactRef) => {
444
+ const {
445
+ className,
446
+ container,
447
+ label,
448
+ title,
449
+ tag = 'div',
450
+ ...styleProps
451
+ }: LabIcon.IProps = { ...this._props, ...props };
452
+
453
+ // set up component state via useState hook
454
+ const [, setId] = React.useState(this._uuid);
455
+
456
+ // subscribe to svg replacement via useEffect hook
457
+ React.useEffect(() => {
458
+ const onSvgReplaced = () => {
459
+ setId(this._uuid);
460
+ };
461
+
462
+ this._svgReplaced.connect(onSvgReplaced);
463
+
464
+ // specify cleanup callback as hook return
465
+ return () => {
466
+ this._svgReplaced.disconnect(onSvgReplaced);
467
+ };
468
+ });
469
+
470
+ // make it so that tag can be used as a jsx component
471
+ const Tag = tag;
472
+
473
+ // ensure that svg html is valid
474
+ if (!(this.svgInnerHTML && this.svgReactAttrs)) {
475
+ // bail if failing silently
476
+ return <></>;
477
+ }
478
+
479
+ const svgComponent = (
480
+ <svg
481
+ {...this.svgReactAttrs}
482
+ dangerouslySetInnerHTML={{ __html: this.svgInnerHTML }}
483
+ ref={ref}
484
+ />
485
+ );
486
+
487
+ if (container) {
488
+ Private.initContainer({ container, className, styleProps, title });
489
+
490
+ return (
491
+ <React.Fragment>
492
+ {svgComponent}
493
+ {label}
494
+ </React.Fragment>
495
+ );
496
+ } else {
497
+ return (
498
+ <Tag
499
+ className={
500
+ className || styleProps
501
+ ? classes(className, LabIconStyle.styleClass(styleProps))
502
+ : undefined
503
+ }
504
+ title={title}
505
+ >
506
+ {svgComponent}
507
+ {label}
508
+ </Tag>
509
+ );
510
+ }
511
+ }
512
+ );
513
+
514
+ component.displayName = `LabIcon_${displayName}`;
515
+ return component;
516
+ }
517
+
518
+ protected _initRender({
519
+ render,
520
+ unrender
521
+ }: Partial<VirtualElement.IRenderer>): void {
522
+ if (render) {
523
+ this.render = render;
524
+ if (unrender) {
525
+ this.unrender = unrender;
526
+ }
527
+ } else if (unrender) {
528
+ console.warn(
529
+ 'In _initRender, ignoring unrender arg since render is undefined'
530
+ );
531
+ }
532
+ }
533
+
534
+ protected _initSvg({
535
+ title,
536
+ uuid
537
+ }: { title?: string; uuid?: string } = {}): HTMLElement | null {
538
+ const svgElement = LabIcon.resolveSvg(this);
539
+
540
+ if (!svgElement) {
541
+ // bail on null svg element
542
+ return svgElement;
543
+ }
544
+
545
+ if (svgElement.tagName !== 'parsererror') {
546
+ // svgElement is an actual svg node, augment it
547
+ svgElement.dataset.icon = this.name;
548
+
549
+ if (uuid) {
550
+ svgElement.dataset.iconId = uuid;
551
+ }
552
+
553
+ if (title) {
554
+ Private.setTitleSvg(svgElement, title);
555
+ }
556
+ }
557
+
558
+ return svgElement;
559
+ }
560
+
561
+ readonly name: string;
562
+
563
+ /**
564
+ * A React component that will create the icon.
565
+ *
566
+ * @param className - a string that will be used as the class
567
+ * of the container element. Overrides any existing class
568
+ *
569
+ * @param container - a preexisting DOM element that
570
+ * will be used as the container for the svg element
571
+ *
572
+ * @param label - text that will be displayed adjacent
573
+ * to the icon
574
+ *
575
+ * @param title - a tooltip for the icon
576
+ *
577
+ * @param tag - if container is not explicitly
578
+ * provided, this tag will be used when creating the container
579
+ *
580
+ * @param stylesheet - optional string naming a builtin icon
581
+ * stylesheet, for example 'menuItem' or `statusBar`. Can also be an
582
+ * object defining a custom icon stylesheet, or a list of builtin
583
+ * stylesheet names and/or custom stylesheet objects. If array,
584
+ * the given stylesheets will be merged.
585
+ *
586
+ * See @jupyterlab/ui-components/src/style/icon.ts for details
587
+ *
588
+ * @param elementPosition - optional position for the inner svg element
589
+ *
590
+ * @param elementSize - optional size for the inner svg element.
591
+ * Set to 'normal' to get a standard 16px x 16px icon
592
+ *
593
+ * @param ...elementCSS - all additional args are treated as
594
+ * overrides for the CSS props applied to the inner svg element
595
+ *
596
+ * @param ref - forwarded to the ref prop of the icon's svg element
597
+ */
598
+ readonly react: LabIcon.IReact;
599
+
600
+ protected _className: string;
601
+ protected _loading: boolean;
602
+ protected _props: LabIcon.IProps = {};
603
+ protected _svgReplaced = new Signal<this, void>(this);
604
+ protected _svgstr: string;
605
+ protected _uuid: string;
606
+
607
+ /**
608
+ * Cache for svg parsing intermediates
609
+ * - undefined: the cache has not yet been populated
610
+ * - null: a valid, but empty, value
611
+ */
612
+ protected _svgElement: HTMLElement | null | undefined = undefined;
613
+ protected _svgInnerHTML: string | null | undefined = undefined;
614
+ protected _svgReactAttrs: any | null | undefined = undefined;
615
+ }
616
+
617
+ /**
618
+ * A namespace for LabIcon statics.
619
+ */
620
+ export namespace LabIcon {
621
+ /** ***********
622
+ * interfaces *
623
+ *************/
624
+
625
+ /**
626
+ * The simplest possible interface for defining a generic icon.
627
+ */
628
+ export interface IIcon extends IRenderMime.LabIcon.IIcon {}
629
+
630
+ export interface IRendererOptions {
631
+ attrs?: ElementAttrs;
632
+ children?: ReadonlyArray<VirtualNode>;
633
+ props?: IProps;
634
+ }
635
+
636
+ /**
637
+ * The ILabIcon interface. Outside of this interface the actual
638
+ * implementation of LabIcon may vary
639
+ */
640
+ export interface ILabIcon extends IIcon, VirtualElement.IRenderer {}
641
+
642
+ /**
643
+ * Interface defining the parameters to be passed to the LabIcon
644
+ * constructor
645
+ */
646
+ export interface IOptions extends IIcon, Partial<VirtualElement.IRenderer> {}
647
+
648
+ /**
649
+ * The input props for creating a new LabIcon
650
+ */
651
+ export interface IProps extends LabIconStyle.IProps {
652
+ /**
653
+ * Extra classNames. Used in addition to the typestyle className to
654
+ * set the className of the icon's outermost container node
655
+ */
656
+ className?: string;
657
+
658
+ /**
659
+ * The icon's outermost node, which acts as a container for the actual
660
+ * svg node. If container is not supplied, it will be created
661
+ */
662
+ container?: HTMLElement;
663
+
664
+ /**
665
+ * Optional text label that will be added as a sibling to the icon's
666
+ * svg node
667
+ */
668
+ label?: string;
669
+
670
+ /**
671
+ * HTML element tag used to create the icon's outermost container node,
672
+ * if no container is passed in
673
+ */
674
+ tag?: 'div' | 'span';
675
+
676
+ /**
677
+ * Optional title that will be set on the icon's outermost container node
678
+ */
679
+ title?: string;
680
+ }
681
+
682
+ export interface IResolverProps {
683
+ icon?: IMaybeResolvable;
684
+ iconClass?: string;
685
+ fallback?: LabIcon;
686
+ }
687
+
688
+ /** ******
689
+ * types *
690
+ *********/
691
+
692
+ /**
693
+ * A type that can be resolved to a LabIcon instance.
694
+ */
695
+ export type IResolvable = IRenderMime.LabIcon.IResolvable;
696
+
697
+ /**
698
+ * A type that maybe can be resolved to a LabIcon instance.
699
+ */
700
+ export type IMaybeResolvable =
701
+ | IResolvable
702
+ | VirtualElement.IRenderer
703
+ | undefined;
704
+
705
+ /**
706
+ * The type of the svg node ref that can be passed into icon React components
707
+ */
708
+ export type IReactRef = React.RefObject<SVGElement>;
709
+
710
+ /**
711
+ * The properties that can be passed into the React component stored in
712
+ * the .react field of a LabIcon.
713
+ */
714
+ export type IReactProps = IProps & React.RefAttributes<SVGElement>;
715
+
716
+ /**
717
+ * The complete type of the React component stored in the .react
718
+ * field of a LabIcon.
719
+ */
720
+ export type IReact = React.ForwardRefExoticComponent<IReactProps>;
721
+ }
722
+
723
+ namespace Private {
724
+ export function blankElement({
725
+ className = '',
726
+ container,
727
+ label,
728
+ title,
729
+ tag = 'div',
730
+ ...styleProps
731
+ }: LabIcon.IProps): HTMLElement {
732
+ if (container?.className === className) {
733
+ // nothing needs doing, return the icon node
734
+ return container;
735
+ }
736
+
737
+ if (container) {
738
+ // take ownership by removing any existing children
739
+ while (container.firstChild) {
740
+ container.firstChild.remove();
741
+ }
742
+ } else {
743
+ // create a container if needed
744
+ container = document.createElement(tag);
745
+ }
746
+ if (label != null) {
747
+ container.textContent = label;
748
+ }
749
+ Private.initContainer({ container, className, styleProps, title });
750
+
751
+ return container;
752
+ }
753
+
754
+ export const blankReact = React.forwardRef(
755
+ (
756
+ {
757
+ className = '',
758
+ container,
759
+ label,
760
+ title,
761
+ tag = 'div',
762
+ ...styleProps
763
+ }: LabIcon.IProps,
764
+ ref: LabIcon.IReactRef
765
+ ) => {
766
+ // make it so that tag can be used as a jsx component
767
+ const Tag = tag;
768
+
769
+ if (container) {
770
+ initContainer({ container, className, styleProps, title });
771
+
772
+ return <></>;
773
+ } else {
774
+ // if ref is defined, we create a blank svg node and point ref to it
775
+ return (
776
+ <Tag
777
+ className={classes(className, LabIconStyle.styleClass(styleProps))}
778
+ >
779
+ {ref && blankIcon.react({ ref })}
780
+ {label}
781
+ </Tag>
782
+ );
783
+ }
784
+ }
785
+ );
786
+ blankReact.displayName = 'BlankReact';
787
+
788
+ export function initContainer({
789
+ container,
790
+
791
+ className,
792
+ styleProps,
793
+ title
794
+ }: {
795
+ container: HTMLElement;
796
+ className?: string;
797
+ styleProps?: LabIconStyle.IProps;
798
+ title?: string;
799
+ }): string {
800
+ if (title != null) {
801
+ container.title = title;
802
+ }
803
+ const styleClass = LabIconStyle.styleClass(styleProps);
804
+
805
+ if (className != null) {
806
+ // override the container class with explicitly passed-in class + style class
807
+ const classResolved = classes(className, styleClass);
808
+ container.className = classResolved;
809
+ return classResolved;
810
+ } else if (styleClass) {
811
+ // add the style class to the container class
812
+ container.classList.add(styleClass);
813
+ return styleClass;
814
+ } else {
815
+ return '';
816
+ }
817
+ }
818
+
819
+ export function isResolvable(
820
+ icon: LabIcon.IMaybeResolvable
821
+ ): icon is LabIcon.IResolvable {
822
+ return !!(
823
+ icon &&
824
+ (typeof icon === 'string' ||
825
+ ((icon as LabIcon.IIcon).name && (icon as LabIcon.IIcon).svgstr))
826
+ );
827
+ }
828
+
829
+ export function setTitleSvg(svgNode: HTMLElement, title: string): void {
830
+ // add a title node to the top level svg node
831
+ const titleNodes = svgNode.getElementsByTagName('title');
832
+ if (titleNodes.length) {
833
+ titleNodes[0].textContent = title;
834
+ } else {
835
+ const titleNode = document.createElement('title');
836
+ titleNode.textContent = title;
837
+ svgNode.appendChild(titleNode);
838
+ }
839
+ }
840
+
841
+ /**
842
+ * A shim for svgstrs loaded using any loader other than raw-loader.
843
+ * This function assumes that svgstr will look like one of:
844
+ *
845
+ * - the raw contents of an .svg file:
846
+ * <svg...</svg>
847
+ *
848
+ * - a data URL:
849
+ * data:[<mediatype>][;base64],<svg...</svg>
850
+ *
851
+ * See https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs
852
+ */
853
+ export function svgstrShim(svgstr: string, strict: boolean = true): string {
854
+ // decode any uri escaping, condense leading/lagging whitespace,
855
+ // then match to raw svg string
856
+ const [, base64, raw] = decodeURIComponent(svgstr)
857
+ .replace(/>\s*\n\s*</g, '><')
858
+ .replace(/\s*\n\s*/g, ' ')
859
+ .match(
860
+ strict
861
+ ? // match based on data url schema
862
+ /^(?:data:.*?(;base64)?,)?(.*)/
863
+ : // match based on open of svg tag
864
+ /(?:(base64).*)?(<svg.*)/
865
+ )!;
866
+
867
+ // decode from base64, if needed
868
+ return base64 ? atob(raw) : raw;
869
+ }
870
+
871
+ /**
872
+ * TODO: figure out story for independent Renderers.
873
+ * Base implementation of IRenderer.
874
+ */
875
+ export class Renderer implements VirtualElement.IRenderer {
876
+ constructor(
877
+ protected _icon: LabIcon,
878
+ protected _rendererOptions?: LabIcon.IRendererOptions
879
+ ) {}
880
+
881
+ // eslint-disable-next-line
882
+ render(container: HTMLElement, options?: LabIcon.IRendererOptions): void {}
883
+ unrender?(container: HTMLElement, options?: LabIcon.IRendererOptions): void;
884
+ }
885
+
886
+ /**
887
+ * TODO: figure out story for independent Renderers.
888
+ * Implementation of IRenderer that creates the icon svg node
889
+ * as a DOM element.
890
+ */
891
+ export class ElementRenderer extends Renderer {
892
+ render(container: HTMLElement, options?: LabIcon.IRendererOptions): void {
893
+ let label = options?.children?.[0];
894
+ // narrow type of label
895
+ if (typeof label !== 'string') {
896
+ label = undefined;
897
+ }
898
+
899
+ this._icon.element({
900
+ container,
901
+ label,
902
+ ...this._rendererOptions?.props,
903
+ ...options?.props
904
+ });
905
+ }
906
+ }
907
+
908
+ /**
909
+ * TODO: figure out story for independent Renderers.
910
+ * Implementation of IRenderer that creates the icon svg node
911
+ * as a React component.
912
+ */
913
+ export class ReactRenderer extends Renderer {
914
+ render(container: HTMLElement, options?: LabIcon.IRendererOptions): void {
915
+ let label = options?.children?.[0];
916
+ // narrow type of label
917
+ if (typeof label !== 'string') {
918
+ label = undefined;
919
+ }
920
+
921
+ const icon = this._icon;
922
+
923
+ if (this._rootDOM !== null) {
924
+ this._rootDOM.unmount();
925
+ }
926
+ this._rootDOM = createRoot(container);
927
+ this._rootDOM.render(
928
+ <icon.react
929
+ container={container}
930
+ label={label}
931
+ {...{ ...this._rendererOptions?.props, ...options?.props }}
932
+ />
933
+ );
934
+ }
935
+
936
+ unrender(container: HTMLElement): void {
937
+ if (this._rootDOM !== null) {
938
+ this._rootDOM.unmount();
939
+ this._rootDOM = null;
940
+ }
941
+ }
942
+
943
+ private _rootDOM: Root | null = null;
944
+ }
945
+ }
946
+
947
+ // need to be at the bottom since constructor depends on Private
948
+ export const badIcon = new LabIcon({
949
+ name: 'ui-components:bad',
950
+ svgstr: badSvgstr
951
+ });
952
+ export const blankIcon = new LabIcon({
953
+ name: 'ui-components:blank',
954
+ svgstr: blankSvgstr
955
+ });