add(widgets) fullscreen widget #8024

chrisgervang · 2023-07-25T20:58:25Z

Background

A fullscreen widget adds a button which users can click to make their map full screen. Click it again to exit full screen.

Design Goals

themes.ts provides 4 built-in themes, and the getting started example shows how these can be applied.

import {Deck} from '@deck.gl/core';
import {FullscreenWidget, DarkTheme} from '@deck.gl/widgets';

new Deck({
  ...
  widgets: [new FullscreenWidget({ style: DarkTheme })
})

With CSS variables it's possible for applications to make customizations, such as:

Light and dark mode (i.e. prefers-color-scheme media-query, or prop override)
Desktop/mobile sizes (i.e. max-width media-query, or prop override)
Total visual customization, such as glass or flat
Branding, such as coloring, shadows, corners, etc

Implementation Goals

Provide css stylesheet via NPM for applications to include
Themable with CSS variables and class selectors.
VanillaJS interface with preact UI framework internally to minimize complexity and bundle size.
For icons, prefer inline SVG over heavy icon fonts

Compatibility

Currently the widget assumes the Fullscreen API is supported without prefixes since it's a mature API at this point. If it's not, then a "pseudo" fullscreen is styled with css.

Change List

Adds FullscreenWidget
Adds widgets getting started example
docs

chrisgervang · 2023-07-25T21:46:43Z

Please leave design comments in our prototype. Open to suggestions!

chrisgervang · 2023-07-26T17:04:15Z

Learning a bit more about CSS variables. They aren't supported inside media queries directly, but a combination of JS and CSS can be used. See discussion.

It'd be ideal to keep variable names shorter, such as --background vs. --deckgl-widget-background. Variables can be scoped with selectors such as .deckgl-widget (or similar) instead of :root. It can be any selector name an application likely doesn't already use.

Supporting browsers that lack css variable support is straightforward. Just define each style twice with and without a variable, and the cascading will apply the latter "valid" property.

modules/widgets/src/fullscreen-widget.ts

ibgreen · 2023-07-26T18:53:56Z

examples/get-started/pure-js/basic/app.js

@@ -57,5 +58,6 @@ new Deck({
      getTargetColor: [200, 0, 80],
      getWidth: 1
    })
-  ]
+  ],
+  _widgets: [new FullscreenWidget()]


Assume you will create a new example for effects.

@Pessimistress suggested I add to the getting started, but I'm not sure if this is what she meant.

You should add a separate example unless you think it's a good functionality to surface on all the examples. Each get-started flavor (pure-js, react, script) demonstrate exactly the same functionality.

modules/widgets/src/fullscreen-widget.ts

Co-authored-by: Ib Green <ib@foursquare.com>

modules/widgets/src/fullscreen-widget.ts

ibgreen

Some thoughts:

Do we have provisions for declaratively setting props on this component (let's say that the component offered a hideNavigationUI prop and the app wanted to change that after creating the component.
What if the app programmatically wants to active the effect that an interactive widget controls. Let's say that the app wanted to trigger full screen, how would it do that?
Docs - In documentation mention that this feature is not available on iPhones?
https://caniuse.com/?search=requestFullscreen
Tests - testing the fullscreen effect may be overkill, but at least add the control to the DOM and and remove it when testing under browser?

modules/widgets/src/fullscreen-widget.ts

chrisgervang · 2023-08-06T16:42:32Z

Thanks for the comments, @ibgreen. I'll take these into account as iteration continues in this PR. In the meantime, let us know if you have comments on #8023 since that's about to merge in.

chrisgervang · 2023-08-10T14:13:49Z

Evaluated RE:DOM as a lightweight html-in-js solution that is supposed to offer a JSX syntax. JSX works fine without typescript in this isolated example I made, but I'm not figuring out how to get redom JSX to work with typescript in this other example.

RE:DOM and typescript don't seem to be pretty commonly documented together. And babel seems to have moved on to a new way to building jsx plugins, which RE:DOM doesn't implement.

Resouces

Setup notes:
yarn add babel-plugin-transform-redom-jsx babel-plugin-transform-react-jsx --dev -W

// babel.config.js
...
plugins: [
  "babel-plugin-transform-redom-jsx",
  [
    "transform-react-jsx",
    {
      "pragma": "el"
    }
  ]
]

// tsconfig.json
"compilerOptions": {
  "jsx": "preserve",
  "jsxFactory": "el"
  ...
},

modules/widgets/src/fullscreen-widget.tsx

ibgreen · 2023-08-16T20:13:46Z

modules/widgets/package.json

@@ -30,7 +30,8 @@
    "prepublishOnly": "npm run build-bundle && npm run build-bundle -- --env=dev"
  },
  "dependencies": {
-    "@babel/runtime": "^7.0.0"
+    "@babel/runtime": "^7.0.0",
+    "preact": "^10.17.0"


Just curious, I haven't really being paying attention. Are we using a react style library for our pure-js implementation? And then we will have react wrappers on top?

I'm pretty certain we don't want the complexity or bundle size of react, but I like its api style.

My goal has been to pick something as close to the DOM as we can while also providing some convenience over document.createElement. preact seems to serve this niche well... It give us the ability to make basic components with JSX, and implements a thin virtual dom only adding 3kb to the bundle.

Re: react wrappers, I think of a widget as a deck component that happens to have UI. In a sense, how the UI is built within it is ideally isolated from other UI on the page so that deck can manage it. Let's say we used react to make UI widgets in @deckgl/widgets... I'd still ideally want them to create their own react root separate from the rest of application and other widgets. This way all integrations work through the same interface.

Understood and I agree with the principle that widgets should be free to choose implementation as long as they are externally independent. That said, I would not be happy to see a pure-js deck.gl module have react as a dependency in its package.json. I would think twice before using that in a pure-js app.

For a community widget that could be a different story of course.

preact seems like a reasonable choice.

modules/widgets/src/fullscreen-widget.tsx

Pessimistress · 2023-09-09T21:56:19Z

modules/widgets/src/fullscreen-widget.tsx

+    const el = document.createElement('div');
+    el.classList.add('deckgl-widget', 'deckgl-widget-fullscreen');
+    if (className) el.classList.add(className);
+    Object.entries(style).map(([key, value]) => el.style.setProperty(key, value));


This is how Deck applies style: https://github.com/visgl/deck.gl/blob/master/modules/core/src/lib/deck.ts#L734

I have not tested it but the two approaches seem equivalent?
https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration/setProperty#alternative_usage

I started with that, but it doesn't work for css variables.

Object.assign(el.style, this.props.style); results in no variables applied to the middle widget.

el.style.setProperty has inline styles:

I think we need to change how Deck does it so the theme variables will work.

chrisgervang · 2023-09-09T22:31:04Z

examples/get-started/pure-js/widgets/app.js

+    new FullscreenWidget({}),
+    new FullscreenWidget({id: 'themed', style: widgetTheme}), 
+    new FullscreenWidget({id: 'purple', className: 'purple'})


@Pessimistress I was thinking of move these variations to a test app. I want to maintain coverage for edge cases somewhere, and keep getting started very simple. Thoughts?

chrisgervang · 2023-09-17T21:21:12Z

Users may want to replace the icons, so I've moved them to CSS. To replace with your own we'll document:

Icons are replaceable and their colors can be customized with CSS variables.

Prepare your icons as SVG urls for a CSS mask-image.
The color of embedded in your SVG will be ignored, but ensure it isn’t transparent. Set the color with the appropriate CSS variable.
Replace the icon with CSS variables like --icon-fullscreen-enter.

into chr/fullscreen-widget

chrisgervang · 2023-09-23T03:38:25Z

docs/api-reference/widgets/overview.md

@Pessimistress, added sections for replacing icons and made other adjustments. Any comments?

cc @ilyabo, @felixpalmer, @ibgreen

chrisgervang added 2 commits July 25, 2023 13:02

add(deck) _widget prop

fc6be2c

add(widgets) fullscreen widget scaffold

cd67293

chrisgervang requested a review from Pessimistress July 25, 2023 20:58

ibgreen reviewed Jul 26, 2023

View reviewed changes

chrisgervang and others added 2 commits July 27, 2023 12:18

Update modules/widgets/src/fullscreen-widget.ts

18835f1

Co-authored-by: Ib Green <ib@foursquare.com>

Update modules/widgets/src/fullscreen-widget.ts

2fa64ad

Co-authored-by: Ib Green <ib@foursquare.com>

Pessimistress force-pushed the chr/deck-widgets-prop branch from fc6be2c to f783461 Compare August 3, 2023 22:59

chrisgervang commented Aug 4, 2023

View reviewed changes

modules/widgets/src/fullscreen-widget.ts Outdated Show resolved Hide resolved

chrisgervang and others added 4 commits August 4, 2023 15:55

add(deck) _widget prop

fceab53

declarative widgets api

bfa10b6

Add comments

adfc21a

fix test

46be41a

Pessimistress force-pushed the chr/deck-widgets-prop branch from b00ae70 to 46be41a Compare August 4, 2023 22:55

simplify widget api

f37b35e

ibgreen approved these changes Aug 6, 2023

View reviewed changes

modules/widgets/src/fullscreen-widget.ts Outdated Show resolved Hide resolved

chrisgervang added 5 commits August 8, 2023 12:59

docs

024d1bc

Merge branch 'master' into chr/deck-widgets-prop

3caa7e8

Merge branch 'chr/deck-widgets-prop' into chr/fullscreen-widget

e07fd97

add(core) export types

debbf1e

Merge branch 'chr/deck-widgets-prop' into chr/fullscreen-widget

f43cfdd

Base automatically changed from chr/deck-widgets-prop to master August 15, 2023 19:28

chrisgervang added 2 commits August 15, 2023 13:32

add(examples) widgets example

ed185ff

add(widgets) build with preact jsx

f135eca

ibgreen reviewed Aug 16, 2023

View reviewed changes

chrisgervang added 2 commits August 16, 2023 15:38

add(widget) fullscreen button + styles

a5cd7b4

add(widget) fullscreen optional container

efd612e

icons, icon variables, onfullscreen handler, pseudo-fullscreen

4791fb8

Pessimistress reviewed Sep 9, 2023

View reviewed changes

docs and style examples

a6f6268

chrisgervang commented Sep 9, 2023

View reviewed changes

chrisgervang and others added 8 commits September 9, 2023 15:40

comments

24bf325

Merge branch 'master' into chr/fullscreen-widget

73afafd

types

61d2f55

luma core

bca3b89

lints

17b6c13

Merge branch 'master' into chr/fullscreen-widget

eebc3ad

drop gl

993d850

Implement icons in CSS as replaceable masks

ed1906d

chrisgervang and others added 6 commits September 22, 2023 16:28

lint

814762f

Merge branch 'master' into chr/fullscreen-widget

9d0ecc0

docs

5f70324

Merge branch 'chr/fullscreen-widget' of https://github.com/visgl/deck.gl

cb72e2c

into chr/fullscreen-widget

use getCanvas

59b1a56

icon docs

03dda1e

chrisgervang commented Sep 23, 2023

View reviewed changes

chrisgervang and others added 4 commits September 22, 2023 17:44

docs

254b319

standard mask-image

01d5c39

Merge branch 'master' into chr/fullscreen-widget

e30fc53

remove viewId, add stateful labels

c641626

chrisgervang merged commit 6d2c4b9 into master Sep 25, 2023
2 checks passed

chrisgervang mentioned this pull request Sep 25, 2023

Add Zoom and Compass widgets #8072

Merged

Pessimistress pushed a commit that referenced this pull request Oct 5, 2023

add(widgets) fullscreen widget (#8024)

d03dc5a

amarant mentioned this pull request Oct 7, 2023

@deck.gl/widgets v8.10.0-alpha.4 use React.createElement instead of the preact jsxFactory h #8182

Closed

7 tasks

Pessimistress deleted the chr/fullscreen-widget branch October 13, 2023 17:25

chrisgervang mentioned this pull request Feb 9, 2024

v9 Tracker #7457

Closed

14 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

add(widgets) fullscreen widget #8024

add(widgets) fullscreen widget #8024

chrisgervang commented Jul 25, 2023 •

edited

Loading

chrisgervang commented Jul 25, 2023

chrisgervang commented Jul 26, 2023 •

edited

Loading

ibgreen Jul 26, 2023

chrisgervang Jul 27, 2023

Pessimistress Jul 29, 2023

ibgreen left a comment

chrisgervang commented Aug 6, 2023

chrisgervang commented Aug 10, 2023

ibgreen Aug 16, 2023

chrisgervang Aug 16, 2023

ibgreen Aug 16, 2023

Pessimistress Sep 9, 2023

chrisgervang Sep 9, 2023

chrisgervang Sep 9, 2023

Pessimistress Sep 9, 2023

chrisgervang commented Sep 17, 2023

chrisgervang Sep 23, 2023

chrisgervang Sep 23, 2023

add(widgets) fullscreen widget #8024

add(widgets) fullscreen widget #8024

Conversation

chrisgervang commented Jul 25, 2023 • edited Loading

Background

Design Goals

Implementation Goals

Compatibility

Change List

chrisgervang commented Jul 25, 2023

chrisgervang commented Jul 26, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ibgreen left a comment

Choose a reason for hiding this comment

chrisgervang commented Aug 6, 2023

chrisgervang commented Aug 10, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisgervang commented Sep 17, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisgervang commented Jul 25, 2023 •

edited

Loading

chrisgervang commented Jul 26, 2023 •

edited

Loading