Add documentation, CSS, Bento prefix for bento-soundcloud/`BentoS…

…oundcloud` (#36094) * Rename component with Bento prefix * Add documentation * Add CSS * amp-soundcloud -> bento-soundcloud
ampproject · Sep 20, 2021 · ab80a38 · ab80a38
1 parent 71f17a6
commit ab80a38
Show file tree

Hide file tree

Showing 9 changed files with 335 additions and 11 deletions.
diff --git a/build-system/compile/bundles.config.extensions.json b/build-system/compile/bundles.config.extensions.json
@@ -926,6 +926,7 @@
     "version": "1.0",
     "latestVersion": "0.1",
     "options": {
+      "hasCss": true,
       "npm": true,
       "wrapper": "bento"
     }

diff --git a/extensions/amp-soundcloud/0.1/amp-soundcloud.md b/extensions/amp-soundcloud/0.1/amp-soundcloud.md
@@ -0,0 +1,72 @@
+---
+$category@: media
+formats:
+  - websites
+teaser:
+  text: Displays a Soundcloud clip.
+---
+
+# amp-soundcloud
+
+## Examples
+
+With the responsive layout, the `width` and `height` from the example should yield correct layouts for 1:1 aspect ratio embeds:
+
+Visual Mode:
+
+```html
+<amp-soundcloud
+  width="480"
+  height="480"
+  layout="responsive"
+  data-trackid="243169232"
+  data-visual="true"
+></amp-soundcloud>
+```
+
+Classic Mode:
+
+```html
+<amp-soundcloud
+  width="480"
+  height="480"
+  layout="responsive"
+  data-trackid="243169232"
+  data-color="ff5500"
+></amp-soundcloud>
+```
+
+## Attributes
+
+<table>
+  <tr>
+    <td width="40%"><strong>data-trackid</strong></td>
+    <td>This attribute is required if <code>data-playlistid</code> is not defined.<br />
+The value for this attribute is the ID of a track, an integer.</td>
+  </tr>
+  <tr>
+    <td width="40%"><strong>data-playlistid</strong></td>
+    <td>This attribute is required if <code>data-trackid</code> is not defined.
+The value for this attribute is the ID of a playlist, an integer.</td>
+  </tr>
+  <tr>
+    <td width="40%"><strong>data-secret-token (optional)</strong></td>
+    <td>The secret token of the track, if it is private.</td>
+  </tr>
+  <tr>
+    <td width="40%"><strong>data-visual (optional)</strong></td>
+    <td>If set to <code>true</code>, displays full-width "Visual" mode; otherwise, it displays as "Classic" mode. The default value is <code>false</code>.</td>
+  </tr>
+  <tr>
+    <td width="40%"><strong>data-color (optional)</strong></td>
+    <td>This attribute is a custom color override for the "Classic" mode. The attribute is ignored in "Visual" mode. Specify a hexadecimal color value, without the leading # (e.g., <code>data-color="e540ff"</code>).</td>
+  </tr>
+  <tr>
+    <td width="40%"><strong>width and height</strong></td>
+    <td>The layout for <code>amp-soundcloud</code> is set to <code>fixed-height</code> and it fills all of the available horizontal space. This is ideal for the "Classic" mode, but for "Visual" mode, it's recommended that the height is 300px, 450px or 600px, as per Soundcloud embed code. This will allow the clip's internal elements to resize properly on mobile.</td>
+  </tr>
+</table>
+
+## Validation
+
+See [amp-soundcloud rules](https://github.com/ampproject/amphtml/blob/main/extensions/amp-soundcloud/validator-amp-soundcloud.protoascii) in the AMP validator specification.
diff --git a/extensions/amp-soundcloud/1.0/README.md b/extensions/amp-soundcloud/1.0/README.md
@@ -0,0 +1,224 @@
+---
+$category@: media
+formats:
+  - websites
+teaser:
+  text: Displays a Soundcloud clip.
+---
+
+# Bento Soundcloud
+
+## Usage
+
+The Bento Soundcloud component allows you to embed a Soundcloud clip. Use it as a web component [`<bento-soundcloud>`](#web-component), or a Preact/React functional component [`<BentoSoundcloud>`](#preact/react-Component).
+
+### Web Component
+
+You must include each Bento component's required CSS library to guarantee proper loading and before adding custom styles. Or use the light-weight pre-upgrade styles available inline. See [Layout and style](#layout-and-style).
+
+The examples below demonstrate use of the `<bento-soundcloud>` web component.
+
+#### Example: Import via npm
+
+[example preview="top-frame" playground="false"]
+
+Install via npm:
+
+```sh
+npm install @ampproject/bento-soundcloud
+```
+
+```javascript
+import '@ampproject/bento-soundcloud';
+```
+
+[/example]
+
+#### Example: Include via `<script>`
+
+[example preview="top-frame" playground="false"]
+
+```html
+<head>
+  <script src="https://cdn.ampproject.org/custom-elements-polyfill.js"></script>
+  <!-- These styles prevent Cumulative Layout Shift on the unupgraded custom element -->
+  <style data-bento-boilerplate>
+    bento-soundcloud {
+      display: block;
+      overflow: hidden;
+      position: relative;
+    }
+  </style>
+  <script async src="https://cdn.ampproject.org/v0/bento-soundcloud-1.0.js"></script>
+  <style>
+    bento-soundcloud {
+      aspect-ratio: 1;
+    }
+  </style>
+</head>
+<bento-soundcloud
+  id="my-track"
+  data-trackid="243169232"
+  data-visual="true"
+></bento-soundcloud>
+<div class="buttons" style="margin-top: 8px;">
+  <button id="change-track">
+    Change track
+  </button>
+</div>
+
+<script>
+  (async () => {
+    const soundcloud = document.querySelector('#my-track');
+    await customElements.whenDefined('bento-soundcloud');
+
+    // set up button actions
+    document.querySelector('#change-track').onclick = () => {
+      soundcloud.setAttribute('data-trackid', '243169232')
+      soundcloud.setAttribute('data-color', 'ff5500')
+      soundcloud.removeAttribute('data-visual')
+    }
+  })();
+</script>
+```
+
+[/example]
+
+#### Layout and style
+
+Each Bento component has a small CSS library you must include to guarantee proper loading without [content shifts](https://web.dev/cls/). Because of order-based specificity, you must manually ensure that stylesheets are included before any custom styles.
+
+```html
+<link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/bento-soundcloud-1.0.css">
+```
+
+Alternatively, you may also make the light-weight pre-upgrade styles available inline:
+
+```html
+<style data-bento-boilerplate>
+  bento-soundcloud {
+    display: block;
+    overflow: hidden;
+    position: relative;
+  }
+</style>
+```
+
+**Container type**
+
+The `bento-soundcloud` component has a defined layout size type. To ensure the component renders correctly, be sure to apply a size to the component and its immediate children (slides) via a desired CSS layout (such as one defined with `height`, `width`, `aspect-ratio`, or other such properties):
+
+```css
+bento-soundcloud {
+  height: 100px;
+  width: 100%;
+}
+```
+
+#### Attributes
+
+<table>
+  <tr>
+    <td width="40%"><strong>data-trackid</strong></td>
+    <td>This attribute is required if <code>data-playlistid</code> is not defined.<br />
+The value for this attribute is the ID of a track, an integer.</td>
+  </tr>
+  <tr>
+    <td width="40%"><strong>data-playlistid</strong></td>
+    <td>This attribute is required if <code>data-trackid</code> is not defined.
+The value for this attribute is the ID of a playlist, an integer.</td>
+  </tr>
+  <tr>
+    <td width="40%"><strong>data-secret-token (optional)</strong></td>
+    <td>The secret token of the track, if it is private.</td>
+  </tr>
+  <tr>
+    <td width="40%"><strong>data-visual (optional)</strong></td>
+    <td>If set to <code>true</code>, displays full-width "Visual" mode; otherwise, it displays as "Classic" mode. The default value is <code>false</code>.</td>
+  </tr>
+  <tr>
+    <td width="40%"><strong>data-color (optional)</strong></td>
+    <td>This attribute is a custom color override for the "Classic" mode. The attribute is ignored in "Visual" mode. Specify a hexadecimal color value, without the leading # (e.g., <code>data-color="e540ff"</code>).</td>
+  </tr>
+</table>
+
+### Preact/React Component
+
+The examples below demonstrate use of the `<BentoSoundcloud>` as a functional component usable with the Preact or React libraries.
+
+#### Example: Import via npm
+
+[example preview="top-frame" playground="false"]
+
+Install via npm:
+
+```sh
+npm install @ampproject/bento-soundcloud
+```
+
+```javascript
+import React from 'react';
+import { BentoSoundcloud } from '@ampproject/bento-soundcloud/react';
+import '@ampproject/bento-soundcloud/styles.css';
+
+function App() {
+  return (
+    <BentoSoundcloud trackId="243169232" visual={true}>
+    </BentoSoundcloud>
+  );
+}
+```
+
+[/example]
+
+#### Layout and style
+
+**Container type**
+
+The `BentoSoundcloud` component has a defined layout size type. To ensure the component renders correctly, be sure to apply a size to the component and its immediate children (slides) via a desired CSS layout (such as one defined with `height`, `width`, `aspect-ratio`, or other such properties). These can be applied inline:
+
+```jsx
+<BentoSoundcloud style={{width: '300px', height: '100px'}} trackId="243169232" visual={true}>
+</BentoSoundcloud>
+```
+
+Or via `className`:
+
+```jsx
+<BentoSoundcloud className='custom-styles' trackId="243169232" visual={true}>
+</BentoSoundcloud>
+```
+
+```css
+.custom-styles {
+  height: 100px;
+  width: 100%;
+}
+```
+
+### Props
+
+<table>
+  <tr>
+    <td width="40%"><strong>trackId</strong></td>
+    <td>This attribute is required if <code>data-playlistid</code> is not defined.<br />
+The value for this attribute is the ID of a track, an integer.</td>
+  </tr>
+  <tr>
+    <td width="40%"><strong>playlistId</strong></td>
+    <td>This attribute is required if <code>data-trackid</code> is not defined.
+The value for this attribute is the ID of a playlist, an integer.</td>
+  </tr>
+  <tr>
+    <td width="40%"><strong>secretToken (optional)</strong></td>
+    <td>The secret token of the track, if it is private.</td>
+  </tr>
+  <tr>
+    <td width="40%"><strong>visual (optional)</strong></td>
+    <td>If set to <code>true</code>, displays full-width "Visual" mode; otherwise, it displays as "Classic" mode. The default value is <code>false</code>.</td>
+  </tr>
+  <tr>
+    <td width="40%"><strong>color (optional)</strong></td>
+    <td>This attribute is a custom color override for the "Classic" mode. The attribute is ignored in "Visual" mode. Specify a hexadecimal color value, without the leading # (e.g., <code>data-color="e540ff"</code>).</td>
+  </tr>
+</table>
diff --git a/extensions/amp-soundcloud/1.0/amp-soundcloud.css b/extensions/amp-soundcloud/1.0/amp-soundcloud.css
@@ -0,0 +1,17 @@
+/*
+ * Pre-upgrade:
+ * - display:block element
+ * - size-defined element
+ */
+amp-soundcloud {
+  display: block;
+  overflow: hidden;
+  position: relative;
+}
+
+/* Pre-upgrade: size-defining element - hide children. */
+amp-soundcloud:not(.i-amphtml-built)
+  > :not([placeholder]):not([slot='i-amphtml-svc']) {
+  display: none;
+  content-visibility: hidden;
+}
diff --git a/extensions/amp-soundcloud/1.0/base-element.js b/extensions/amp-soundcloud/1.0/base-element.js
@@ -1,6 +1,6 @@
 import {PreactBaseElement} from '#preact/base-element';
 
-import {Soundcloud} from './component';
+import {BentoSoundcloud} from './component';
 
 export class BaseElement extends PreactBaseElement {
   /** @override */
@@ -10,7 +10,7 @@ export class BaseElement extends PreactBaseElement {
 }
 
 /** @override */
-BaseElement['Component'] = Soundcloud;
+BaseElement['Component'] = BentoSoundcloud;
 
 /** @override */
 BaseElement['props'] = {

diff --git a/extensions/amp-soundcloud/1.0/component.js b/extensions/amp-soundcloud/1.0/component.js
@@ -13,10 +13,10 @@ const MATCHES_MESSAGING_ORIGIN = (origin) => {
 };
 
 /**
- * @param {!SoundcloudDef.Props} props
+ * @param {!BentoSoundcloudDef.Props} props
  * @return {PreactDef.Renderable}
  */
-export function Soundcloud({
+export function BentoSoundcloud({
   color,
   onLoad,
   playlistId,
@@ -67,7 +67,7 @@ export function Soundcloud({
   // Extract Media ID
   const mediaId = trackId ?? playlistId;
 
-  // Prepare Soundcloud Widget URL for iFrame
+  // Prepare BentoSoundcloud Widget URL for iFrame
   let iframeSrc =
     'https://w.soundcloud.com/player/?' +
     'url=' +

diff --git a/extensions/amp-soundcloud/1.0/component.type.js b/extensions/amp-soundcloud/1.0/component.type.js
@@ -1,7 +1,7 @@
 /** @externs */
 
 /** @const */
-var SoundcloudDef = {};
+var BentoSoundcloudDef = {};
 
 /**
  * @typedef {{
@@ -13,4 +13,4 @@ var SoundcloudDef = {};
  *   onLoad: (function():undefined|undefined),
  * }}
  */
-SoundcloudDef.Props;
+BentoSoundcloudDef.Props;