Remove readonly restriction from StyleInfo interface (#2657)

Co-authored-by: Andrew Jakubowicz <ajakubowicz@google.com>

.changeset/heavy-carrots-thank.md

@@ -0,0 +1,6 @@
+---
+'lit-html': patch
+'lit': patch
+---
+
+Remove readonly restriction from `StyleInfo` interface as addition, deletion, and updating of styles is valid. Expanded `styleMap` documentation with links to lit.dev.

packages/lit-html/src/directives/style-map.ts

@@ -21,7 +21,7 @@ import {
  * for CSSStyleDeclaration like `backgroundColor`.
  */
 export interface StyleInfo {
-  readonly [name: string]: string | undefined | null;
+  [name: string]: string | undefined | null;
 }
 
 class StyleMapDirective extends Directive {
@@ -41,7 +41,7 @@ class StyleMapDirective extends Directive {
     }
   }
 
-  render(styleInfo: StyleInfo) {
+  render(styleInfo: Readonly<StyleInfo>) {
     return Object.keys(styleInfo).reduce((style, prop) => {
       const value = styleInfo[prop];
       if (value == null) {
@@ -111,18 +111,19 @@ class StyleMapDirective extends Directive {
  * A directive that applies CSS properties to an element.
  *
  * `styleMap` can only be used in the `style` attribute and must be the only
- * expression in the attribute. It takes the property names in the `styleInfo`
- * object and adds the property values as CSS properties. Property names with
- * dashes (`-`) are assumed to be valid CSS property names and set on the
- * element's style object using `setProperty()`. Names without dashes are
- * assumed to be camelCased JavaScript property names and set on the element's
- * style object using property assignment, allowing the style object to
- * translate JavaScript-style names to CSS property names.
+ * expression in the attribute. It takes the property names in the
+ * {@link StyleInfo styleInfo} object and adds the property values as CSS
+ * properties. Property names with dashes (`-`) are assumed to be valid CSS
+ * property names and set on the element's style object using `setProperty()`.
+ * Names without dashes are assumed to be camelCased JavaScript property names
+ * and set on the element's style object using property assignment, allowing the
+ * style object to translate JavaScript-style names to CSS property names.
  *
  * For example `styleMap({backgroundColor: 'red', 'border-top': '5px', '--size':
  * '0'})` sets the `background-color`, `border-top` and `--size` properties.
  *
  * @param styleInfo
+ * @see {@link https://lit.dev/docs/templates/directives/#stylemap styleMap code samples on Lit.dev}
  */
 export const styleMap = directive(StyleMapDirective);
 

packages/lit-html/src/test/directives/style-map_test.ts

@@ -134,7 +134,7 @@ suite('styleMap', () => {
   });
 
   test('works when used with the same object', () => {
-    const styleInfo = {marginTop: '2px', 'padding-bottom': '4px'};
+    const styleInfo: StyleInfo = {marginTop: '2px', 'padding-bottom': '4px'};
     renderStyleMap(styleInfo);
     const el = container.firstElementChild as HTMLElement;
     assert.equal(el.style.marginTop, '2px');
@@ -146,6 +146,20 @@ suite('styleMap', () => {
     assert.equal(el.style.paddingBottom, '8px');
   });
 
+  test('works when same object adds and removes properties', () => {
+    const styleInfo: StyleInfo = {marginTop: '2px', 'padding-bottom': '4px'};
+    renderStyleMap(styleInfo);
+    const el = container.firstElementChild as HTMLElement;
+    assert.equal(el.style.marginTop, '2px');
+    assert.equal(el.style.paddingBottom, '4px');
+    assert.equal(el.style.color, '');
+    delete styleInfo['marginTop'];
+    styleInfo.color = 'green';
+    renderStyleMap(styleInfo);
+    assert.equal(el.style.marginTop, '');
+    assert.equal(el.style.color, 'green');
+  });
+
   test('throws when used on non-style attribute', () => {
     assert.throws(() => {
       render(html`<div id="${styleMap({})}"></div>`, container);