deprecate custom properties in favor of parts (google#2370)

Yeelong · May 10, 2021 · 512f488 · 512f488
1 parent b158ecb
commit 512f488
Show file tree

Hide file tree

Showing 4 changed files with 36 additions and 64 deletions.
diff --git a/packages/model-viewer/src/template.ts b/packages/model-viewer/src/template.ts
@@ -316,7 +316,7 @@ canvas.show {
 
   <div class="slot ar-button">
     <slot name="ar-button">
-      <a id="default-ar-button" class="fab"
+      <a id="default-ar-button" part="default-ar-button" class="fab"
           tabindex="2"
           aria-label="View this 3D model up close">
         ${ARGlyph}
@@ -325,7 +325,7 @@ canvas.show {
   </div>
 
   <div class="slot interaction-prompt">
-    <div class="animated-container" part="interaction-prompt">
+    <div class="animated-container">
       <slot name="interaction-prompt" aria-hidden="true">
         ${ControlsPrompt}
       </slot>
@@ -338,15 +338,15 @@ canvas.show {
     <div class="slot progress-bar">
       <slot name="progress-bar">
         <div id="default-progress-bar" aria-hidden="true">
-          <div class="mask"></div>
-          <div class="bar"></div>
+          <div class="mask" part="default-progress-mask"></div>
+          <div class="bar" part="default-progress-bar"></div>
         </div>
       </slot>
     </div>
     
     <div class="slot exit-webxr-ar-button">
       <slot name="exit-webxr-ar-button">
-        <a id="default-exit-webxr-ar-button"
+        <a id="default-exit-webxr-ar-button" part="default-exit-webxr-ar-button"
             tabindex="3"
             aria-label="Exit AR"
             aria-hidden="true">

diff --git a/packages/modelviewer.dev/data/docs.json b/packages/modelviewer.dev/data/docs.json
@@ -76,42 +76,6 @@
           "default": "#fff",
           "options": "valid css background-color"
         }
-      },
-      {
-        "name": "--poster-image",
-        "htmlName": "posterImage",
-        "description": "Sets the  <span class='attribute'>background-image</span> of the  <span class='attribute'>poster</span>. This is currently overridden by the  <span class='attribute'>poster</span> attribute if it is set.",
-        "default": {
-          "default": "none",
-          "options": "valid css background-image"
-        }
-      },
-      {
-        "name": "--progress-bar-color",
-        "htmlName": "progressBarColor",
-        "description": "Sets the  <span class='attribute'>background-color</span> of the progress bar.",
-        "default": {
-          "default": "rgba(0, 0, 0, 0.4)",
-          "options": "valid css background-color"
-        }
-      },
-      {
-        "name": "--progress-bar-height",
-        "htmlName": "progressBarHeight",
-        "description": "Sets the  <span class='attribute'>height</span> of the progress bar.",
-        "default": {
-          "default": "5px",
-          "options": "valid css height"
-        }
-      },
-      {
-        "name": "--progress-mask",
-        "htmlName": "progressMask",
-        "description": "Sets the  <span class='attribute'>background</span> of the progress mask.",
-        "default": {
-          "default": "#fff",
-          "options": "valid css background"
-        }
       }
     ],
     "Properties": [
@@ -237,6 +201,18 @@
         "description": "This event fires while a model, environment, and/or skybox is loading, during both download and processing. The progress of all of these concurrent tasks will be given by a value between 0 and 1: event.detail.totalProgress."
       }
     ],
+    "Parts": [
+      {
+        "name": "default-progress-bar",
+        "htmlName": "defaultProgressBar",
+        "description": "Scope your CSS to <code>model-viewer::part(default-progress-bar)</code> to change the styling of our default progress bar without replacing it wholesale with a slot. Most common would be probably changing the background-color, height, width, and margins (avoid the transform property as that is how the progress is updated)."
+      },
+      {
+        "name": "default-progress-mask",
+        "htmlName": "defaultProgressMask",
+        "description": "Scope your CSS to <code>model-viewer::part(default-progress-mask)</code> to change the styling of our default progress mask without replacing it wholesale with a slot. Most common would be probably setting display: none to turn off the fading haze over the poster during load."
+      }
+    ],
     "Slots": [
       {
         "name": "poster",
@@ -310,15 +286,6 @@
       }
     ],
     "CSS": [
-      {
-        "name": "--ar-button-display",
-        "htmlName": "arButtonDisplay",
-        "description": "Sets the display property of the AR button. Intended to be used to force the button to be hidden. Defaults to block.",
-        "default": {
-          "default": "block",
-          "options": "css display value"
-        }
-      },
       {
         "name": "ar-status",
         "htmlName": "arStatus",
@@ -374,6 +341,18 @@
         "description": "If the user has entered a quick-look AR session on iOS, this event is fired when the action button is tapped. An action button can be defined using URL parameters on the ios-src, see <a href='https://developer.apple.com/documentation/arkit/adding_an_apple_pay_button_or_a_custom_action_in_ar_quick_look'>Apple's documentation</a>."
       }
     ],
+    "Parts": [
+      {
+        "name": "default-ar-button",
+        "htmlName": "defaultArButton",
+        "description": "Scope your CSS to <code>model-viewer::part(default-ar-button)</code> to change the styling of our default Enter AR button without replacing it wholesale with a slot. Most common would be probably changing the position or size using transform and margins."
+      },
+      {
+        "name": "default-exit-webxr-ar-button",
+        "htmlName": "defaultExitWebxrArButton",
+        "description": "Scope your CSS to <code>model-viewer::part(default-exit-webxr-ar-button)</code> to change the styling of our default Exit AR button for WebXR mode without replacing it wholesale with a slot. Most common would be probably changing the position or size using transform and margins."
+      }
+    ],
     "Slots": [
       {
         "name": "ar-button",
@@ -586,17 +565,6 @@
         ]
       }
     ],
-    "CSS": [
-      {
-        "name": "--interaction-prompt-display",
-        "htmlName": "interactionPromptDisplay",
-        "description": "Sets the display property of the interaction prompt. Intended to be used to force the prompt to be hidden.",
-        "default": {
-          "default": "flex",
-          "options": "any valid css display"
-        }
-      }
-    ],
     "Properties": [
       {
         "name": "turntableRotation",

diff --git a/packages/modelviewer.dev/src/docs-and-examples/create-html.ts b/packages/modelviewer.dev/src/docs-and-examples/create-html.ts
@@ -23,15 +23,16 @@ interface Entry {
 }
 
 interface Category {
-  Title: string, Attributes: Entry[], CSS: Entry[], Properties: Entry[],
-      'Static Properties': Entry[], Methods: Entry[], 'Static Methods': Entry[],
-      Events: Entry[], Slots: Entry[],
+  Title: string, Attributes: Entry[], CSS: Entry[], Parts: Entry[],
+      Properties: Entry[], 'Static Properties': Entry[], Methods: Entry[],
+      'Static Methods': Entry[], Events: Entry[], Slots: Entry[],
 }
 
 const CategoryConstant: Category = {
   Title: '',
   Attributes: [],
   CSS: [],
+  Parts: [],
   Properties: [],
   'Static Properties': [],
   Methods: [],

diff --git a/packages/modelviewer.dev/styles/docs.css b/packages/modelviewer.dev/styles/docs.css
@@ -12,6 +12,7 @@ p {
 
 .attribute-name,
 .cs-name,
+.part-name,
 .propertie-name,
 .staticPropertie-name,
 .method-name,
@@ -25,6 +26,7 @@ p {
 
 .attribute-definition,
 .cs-definition,
+.part-definition,
 .propertie-definition,
 .staticPropertie-definition,
 .method-definition,
@@ -40,6 +42,7 @@ p {
 
 .attribute-container,
 .cs-container,
+.part-container,
 .propertie-container,
 .staticPropertie-container,
 .method-container,