Skip to content

Commit 02c99ec

Browse files
kerrishottskerrishotts
committed
first version of 2>3
1 parent c9e6859 commit 02c99ec

File tree

1 file changed

+254
-0
lines changed

1 file changed

+254
-0
lines changed

‎migrations/uxp-2-to-3.md

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
# UXP 2 to 3
2+
3+
XD 20 and below utilized UXP version 2. In XD 21, we're shipping a new version of UXP: Version 3.1. This version is a _huge_ release, and comes with lots of new features of which you'll want to take advantage.
4+
5+
Because the new features in UXP 3.1 are so large, we also introduced a backwards-compatibility mode. _All plugins use backwards-compatibility mode by default_, unless the plugin explicitly opts out. This helps to ensure that most plugins won't suddenly change their appearance and have broken layouts.
6+
7+
> **Info**
8+
>
9+
> All plugins with a `host.minVersion` less than `21` use the UXP backwards compatibility mode. Plugins must explicitly opt-in to using the new layout features in UXP 3.1 by setting a `host.minVersion` of `21`.
10+
11+
Several features in UXP 3.1 are _unavailable_ to plugins running in backwards-compatibility mode, and backwards-compatibility mode **will not last forever**. As such, you'll want to migrate your plugins to UXP 3.1 as soon as possible.
12+
13+
## Layout Engine Improvements
14+
15+
UXP 3.1's layout engine has been improved to make it more compliant with existing web standards.
16+
17+
### Inline Layout
18+
19+
In previous versions of XD (20 and below), all elements rendered using either _block_ or _flex_ layout semantics. In UXP 3.1, we now support _inline_ layout semantics, including `inline-block`.
20+
21+
This means, for example, that you can now easily place inline links or apply different styles within the same paragraph whereas it was difficult to impossible to do so before XD 21.
22+
23+
For example:
24+
25+
```html
26+
<p>For more information about <span style="color: #FF0000; font-weight: bold;">Adobe</span>, visit <a href="https://www.adobe.com">Adobe's website</a>.<p>
27+
```
28+
29+
### Insignificant Whitespace
30+
31+
Furthermore, whitespace between elements is no longer considered significant. In previous versions of XD, it was possible to space elements out by adding additional whitespace. In UXP 3.1, you can only do this if you set the `white-space` CSS property to allow it.
32+
33+
```html
34+
<p>The whitespace is no longer significant</p>
35+
<p style="white-space:pre">But this whitespace is significant.</p>
36+
```
37+
38+
> **Danger**
39+
>
40+
> There is a known issue in XD 21 (UXP 3.1) where white-space between inline elements is also ignored. This means that `<span>Hello</span> <span>World</span>` renders _without_ the space separating "Hello" and "World". This will be fixed in a future release.
41+
42+
### SPANs are no longer leaf elements
43+
One other important result of this change is the fact that `<span>` elements can contain additional elements. For example:
44+
45+
```html
46+
<span>This SPAN contains <span style="font-weight: bold">another span</span>!</span>
47+
```
48+
49+
### `z-index` support
50+
51+
You can also now change an element's stacking order by setting `z-index`.
52+
53+
```css
54+
.menu {
55+
z-index: 99;
56+
}
57+
```
58+
59+
### `object-fit` support
60+
61+
UXP 3.1 also provides the ability to use the `object-fit` property to better control the layout of your elements. You can use `contain` and `cover` values to control if a replaced element should fit within its container or expand to fill it completely (both maintaining the aspect ratio). You can also use `scale-down`, `none`, and `fill`.
62+
63+
For more information, see https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit. The examples in the MDN documentation will work in UXP 3.1.
64+
65+
> **Danger**
66+
>
67+
> Borders and backgrounds may not be drawn as expected with `object-fit`. SVGs may also not be drawn correctly.
68+
69+
70+
## CSS Parsing Improvements
71+
72+
Along with the layout engine improvements, UXP 3.1 also delivers several key improvements to the CSS parser, bringing the parsing on par with the existing CSS standards. While UXP 3.1 does _not_ implement the entire CSS spec, the parsing engine itself now more closely matches the specification.
73+
74+
Improving the CSS parser also enabled UXP 3.1 to support CSS variables, additional units, `calc`, limited Media Queries, `!important`, and more.
75+
76+
### CSS Variables
77+
78+
CSS Variables make it simple to modularize your CSS styles. For example, you could easily create multiple themes using CSS Variables. By changing the variable definition, the styles which rely on the variable are updated automatically.
79+
80+
```html
81+
<style>
82+
.dark {
83+
--text-color: white;
84+
--background-color: black;
85+
}
86+
87+
.light {
88+
--text-color: black;
89+
--background-color: white;
90+
}
91+
92+
.themed {
93+
color: var(--text-color);
94+
background-color: var(--background-color);
95+
}
96+
</style>
97+
<div class="themed light">Hello</div>
98+
<div class="themed dark">There</div>
99+
```
100+
101+
In the above example, "Hello" will be rendered with black text on a white background, and "There" will be rendered with white text on a black background.
102+
103+
### Additional Unit Support
104+
105+
In versions of XD 20 and below, the only supported units were `px` and `%`. Unitless values were interpreted as `px`. In XD 21 and above, many of the CSS units are now supported. As such, unitless values are no longer supported (unless otherwise provided for by the CSS specification).
106+
107+
You can now use `em`, `rem`, `vh`, `vw`, `cm`, `in`, etc., in addition to `px` and `%`.
108+
109+
> **Danger**
110+
>
111+
> If you use `vh` with respect to font sizes, the font size will _not_ update when the viewport height is changed.
112+
113+
### Calculation Support
114+
115+
With the addition of additional unit support, UXP 3.1 also provides the `calc` function, which also works with mixed units. Now you can write an expression like `width: calc(50% - 10px)`.
116+
117+
> **Danger**
118+
>
119+
> `calc` only works for length values. It does not work for colors.
120+
121+
### Media Query Support
122+
123+
UXP 3.1 offers _limited_ support for media queries -- namely queries around the width and height of the viewport.
124+
125+
```css
126+
@media screen and (max-width: 260px) {
127+
input[type=range] {
128+
display: none;
129+
}
130+
}
131+
```
132+
133+
The above CSS will hide sliders whenever the plugin's viewport width is less than 260px.
134+
135+
> **Danger**
136+
>
137+
> Versions of XD 20 and below would _apply_ the styles in a media query, regardless of whether the condition was met. If you used media queries in your CSS, you may need to double check your code to ensure that your plugin renders as expected under UXP 3.1.
138+
139+
### Additional Property Values
140+
141+
The improved CSS Parser also brings the ability to use `unset`, `initial`, `inherit`, and `!important` in your CSS and have them behave as per the specification. Previously these values were not supported.
142+
143+
This means, that if you really need to, you can override styles, like so:
144+
145+
```css
146+
.caption {
147+
color: blue !important;
148+
}
149+
```
150+
151+
> **Danger**
152+
>
153+
> Setting a border color to `unset` is not likely to result in the expected output.
154+
155+
### Linear Gradient Support
156+
157+
The CSS parser now understands the Linear Gradient syntax. For example:
158+
159+
```css
160+
body {
161+
background: linear-gradient(33deg, yellow, purple);
162+
}
163+
```
164+
165+
> **Danger**
166+
>
167+
> Multi-color stops are not supported.
168+
169+
## Other miscellaneous features
170+
171+
* **Outline support**: You can assign an outline to your elements with the `outline` rule.
172+
* **New pseudo-selectors**: `:lang` and `:focus` are now available.
173+
* **Tab index, v1**: Setting `tab-index` to `0` will now cause any element to be focusable. You can **not** yet control the tab order.
174+
* **Improved default for `overflow`**: `overflow` now defaults to `visible`, not `hidden`, as per the web specification.
175+
* Initial SVG support. Only simple SVGs are supported; complex SVGs may render in unexpected ways.
176+
177+
## Backwards Compatibility Mode
178+
179+
When in backwards compatibility mode, UXP and XD will attempt to render it in a manner similar to XD 20 and below. This is not a perfect emulation of previous versions of UXP, but should work for most plugins in most cases.
180+
181+
> **Danger**
182+
>
183+
> *Backward-compatibility mode will _not last forever_*. As such, developers are encouraged to look at their plugin with backward compatibility mode turned off so that they can start to plan for the fixes that will be needed. We don't have a firm timeline on how long backward compatibility mode will be supported, but developers should start taking advantage of the new layout engine as soon as they can feasibly do so.
184+
185+
When in this mode (which is enabled by default unless your manifest specifies your plugin supports XD 21 as a minimum), the following rules are in place:
186+
187+
* Inline layout is ignored (`display: inline[-block]` is disabled).
188+
* `display` is a valid property on elements (instead of `style.display`).
189+
* When using `position: absolute`, and no coordinates are specified, `0x0` is assumed.
190+
* `z-index` is ignored.
191+
* Whitespace is treated as significant
192+
* Unit-less height and width styling is supported
193+
* UXP 2 semantics for `auto` margins.
194+
195+
### Unsupported backwards compatibility
196+
197+
* Semantics in UXP 2 for rendering border radii with percentages is not per web spec. UXP 3.1 renders border radii correctly. This will not be fixed as part of backwards compatibility. The difference is small and does not affect layout (just how round a corner is).
198+
199+
## Considerations when migrating
200+
201+
Migrating from UXP 2 to 3 is not typically difficult. There are some considerations, however, of which you need to be aware.
202+
203+
### Font Rendering Changes
204+
205+
UXP 3.1 introduces uses lower-level font rendering, and this can cause slight differences in layout. Depending on the constraints of your user interface, this may be enough to cause elements to render on more lines or wider than expected.
206+
207+
### Layout Changes
208+
209+
The change from `block` to `inline` layout semantics can cause significant UI changes. If you used `flex` layout to render your plugin UI, you may not notice any difference when using UXP 3.1. However, if your code relied on `block` being the default layout mode, you may find that your layout no longer acts as expected. You can explicitly assign `display: block` to the offending elements, or rework your UI to work with inline layout.
210+
211+
### SPANs are no longer leaf elements
212+
213+
As mentioned above, `<span>` elements can now contain other elements. If your code included elements within `<span>`s, you may find that your UI renders with unexpected styling.
214+
215+
### Media Queries
216+
217+
UXP 2.x would _always_ apply a media query, even if the condition wasn't met. UXP 3.1 will _only_ apply a media query if the condition is met.
218+
219+
### Unitless Values
220+
221+
UXP 2.x would parse unitless values as `px` unless the specification indicated otherwise. UXP 3.1 will treat these as invalid styles, which may cause your UI to render in odd ways. To fix, ensure you always use the correct units.
222+
223+
### Default Stylesheet Changes
224+
225+
The default stylesheet in UXP 3 is different from that provided by UXP 2 and backwards-compatibility mode. This means that your plugin may take on a radically different appearance when not running in backwards-compatibility mode.
226+
227+
_Most_ of the differences in the default stylesheet are due to the presence of the panel insertion point for your plugins. Modal dialogs styling is generally the same. However, there are a few differences that might cause changes in your layout:
228+
229+
* `<label>` is now rendered using `display: inline-flex` by default. This means form elements without a `row` or `column` class will render with the label to the left of the element instead of the label above the element.
230+
* Styles are applied with _less_ specificity. This means it is easier to override the styling of an `<h2>`, for example.
231+
232+
## Quick Feature Summary
233+
234+
New Feature | UXP 2.x | UXP 3.1 (w/o backwards-compatibility)
235+
------------------|------------------|--------------------------
236+
Inline Layout | Unsupported | Enabled
237+
`white-space` | `pre-wrap` | `normal`
238+
`<span>` | Leaf elements | Can contain other elements
239+
`z-index` | Unsupported | Supported
240+
`object-fit` | Unsupported | Supported
241+
CSS Variables | Unsupported | Supported
242+
Units | `px`, `%` | The rest!
243+
`calc` | Unsupported | Supported (for lengths)
244+
Media Queries | Unsupported | Supported (for viewport)
245+
`unset` | Unsupported | Supported
246+
`initial` | Unsupported | Supported
247+
`inherit` | Unsupported | Supported
248+
`!important` | Unsupported | Supported
249+
Linear Gradients | Unsupported | Supported
250+
`outline` | Unsupported | Supported
251+
`:lang`, `:focus` | Unsupported | Supported
252+
`tab-index` | Unsupported | Partially supported
253+
`overflow` | `hidden` | `visible`
254+

0 commit comments

Comments
 (0)