feat(plugins/topics): add labels alias (lowlighter#776) [skip ci]

lowlighter · web-flow · commit 29b445d5b595 · 2022-01-15T18:32:51.000-05:00
diff --git a/source/plugins/topics/README.md b/source/plugins/topics/README.md
@@ -1,21 +1,28 @@
-### 📌 Starred topics
-
-The *topics* plugin displays your [starred topics](https://github.com/stars?filter=topics).
-Check out [GitHub topics](https://github.com/topics) to search interesting topics.
-
+<!--header-->
 <table>
-  <td align="center">
-    <details open><summary>With icons</summary>
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.topics.icons.svg">
-    </details>
-    <details open><summary>With labels</summary>
-      <img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.topics.svg">
-    </details>
-    <img width="900" height="1" alt="">
-  </td>
+  <tr><th colspan="2"><h3>📌 Starred topics</h3></th></tr>
+  <tr><td colspan="2" align="center"><p>This plugin displays <a href="https://github.com/stars?filter=topics">starred topics</a>.
+Check out <a href="https://github.com/topics">GitHub topics</a> to search interesting topics.</p>
+</td></tr>
+  <tr>
+    <th rowspan="3">Supported features<br><sub><a href="metadata.yml">→ Full specification</a></sub></th>
+    <td><a href="/source/templates/classic"><code>📗 Classic template</code></a> <a href="/source/templates/markdown"><code>📒 Markdown template</code></a></td>
+  </tr>
+  <tr>
+    <td><code>👤 Users</code></td>
+  </tr>
+  <tr>
+    <td><i>No tokens are required for this plugin</i></td>
+  </tr>
+  <tr>
+    <td colspan="2" align="center">
+      <details open><summary>With icons</summary><img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.topics.icons.svg" alt=""></img></details>
+      <details open><summary>With labels</summary><img src="https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.topics.svg" alt=""></img></details>
+      <img width="900" height="1" alt="">
+    </td>
+  </tr>
 </table>
-
-This uses puppeteer to navigate through your starred topics page.
+<!--/header-->
 
 #### ➡️ Available options
 
@@ -26,7 +33,8 @@ This uses puppeteer to navigate through your starred topics page.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_topics</code></td>
-    <td rowspan="2">Display starred topics<img width="900" height="1" alt=""></td>
+    <td rowspan="2"><p>Enable topics plugin</p>
+<img width="900" height="1" alt=""></td>
   </tr>
   <tr>
     <td nowrap="nowrap"><b>type:</b> <code>boolean</code>
@@ -35,17 +43,31 @@ This uses puppeteer to navigate through your starred topics page.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_topics_mode</code></td>
-    <td rowspan="2">Plugin mode<img width="900" height="1" alt=""></td>
+    <td rowspan="2"><p>Display mode:</p>
+<ul>
+<li><code>labels</code>: display labels</li>
+<li><code>icons</code>: display icons <em>(topics without icons will be ignored)</em></li>
+<li><code>starred</code>: alias for <code>labels</code></li>
+<li><code>mastered</code>: alias for <code>icons</code></li>
+</ul>
+<img width="900" height="1" alt=""></td>
   </tr>
   <tr>
     <td nowrap="nowrap"><b>type:</b> <code>string</code>
 <br>
 <b>default:</b> starred<br>
-<b>allowed values:</b><ul><li>starred</li><li>icons</li><li>mastered</li></ul></td>
+<b>allowed values:</b><ul><li>labels</li><li>icons</li><li>starred</li><li>mastered</li></ul></td>
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_topics_sort</code></td>
-    <td rowspan="2">Sorting method of starred topics<img width="900" height="1" alt=""></td>
+    <td rowspan="2"><p>Sorting method:</p>
+<ul>
+<li><code>stars</code>: sort by most stars</li>
+<li><code>activity</code>: sort by recent activity</li>
+<li><code>starred</code>: sort by the date you starred them</li>
+<li><code>random</code>: sort topics randomly</li>
+</ul>
+<img width="900" height="1" alt=""></td>
   </tr>
   <tr>
     <td nowrap="nowrap"><b>type:</b> <code>string</code>
@@ -55,14 +77,17 @@ This uses puppeteer to navigate through your starred topics page.
   </tr>
   <tr>
     <td nowrap="nowrap"><code>plugin_topics_limit</code></td>
-    <td rowspan="2">Maximum number of topics to display<img width="900" height="1" alt=""></td>
+    <td rowspan="2"><p>Display limit</p>
+<p>When using <code>plugin_topics_mode: labels</code>, an ellipsis will be displayed</p>
+<img width="900" height="1" alt=""></td>
   </tr>
   <tr>
     <td nowrap="nowrap"><b>type:</b> <code>number</code>
 <i>(0 ≤
 𝑥
 ≤ 20)</i>
 <br>
+<b>zero behaviour:</b> disable</br>
 <b>default:</b> 15<br></td>
   </tr>
 </table>
diff --git a/source/plugins/topics/index.mjs b/source/plugins/topics/index.mjs
@@ -8,6 +8,7 @@ export default async function({login, data, imports, q, account}, {enabled = fal
 
     //Load inputs
     let {sort, mode, limit} = imports.metadata.plugins.topics.inputs({data, account, q})
+    const type = {starred:"labels", labels:"labels", mastered:"icons", icons:"icons"}[mode]
     const shuffle = (sort === "random")
 
     //Start puppeteer and navigate to topics
@@ -51,8 +52,8 @@ export default async function({login, data, imports, q, account}, {enabled = fal
       topics = imports.shuffle(topics)
     }
 
-    //Limit topics (starred mode)
-    if ((mode === "starred") && (limit > 0)) {
+    //Limit topics (labels)
+    if ((type === "labels") && (limit > 0)) {
       console.debug(`metrics/compute/${login}/plugins > topics > keeping only ${limit} topics`)
       const removed = topics.splice(limit)
       if (removed.length)
@@ -72,14 +73,14 @@ export default async function({login, data, imports, q, account}, {enabled = fal
       topic.description = imports.htmlescape(topic.description)
     }
 
-    //Filter topics with icon (mastered mode)
-    if (mode === "mastered") {
+    //Filter topics with icon (icons)
+    if (type === "icons") {
       console.debug(`metrics/compute/${login}/plugins > topics > filtering topics with icon`)
       topics = topics.filter(({icon}) => icon)
     }
 
-    //Limit topics (mastered mode)
-    if ((mode === "mastered") && (limit > 0)) {
+    //Limit topics (icons)
+    if ((type === "icons") && (limit > 0)) {
       console.debug(`metrics/compute/${login}/plugins > topics > keeping only ${limit} topics`)
       topics.splice(limit)
     }
diff --git a/source/plugins/topics/metadata.yml b/source/plugins/topics/metadata.yml
@@ -1,44 +1,59 @@
 name: "📌 Starred topics"
 category: github
+description: |
+  This plugin displays [starred topics](https://github.com/stars?filter=topics).
+  Check out [GitHub topics](https://github.com/topics) to search interesting topics.
+examples:
+  +with icons: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.topics.icons.svg
+  +with labels: https://github.com/lowlighter/metrics/blob/examples/metrics.plugin.topics.svg
 index: 2
 supports:
   - user
 scopes: []
 inputs:
 
-  # Enable or disable plugin
   plugin_topics:
-    description: Display starred topics
+    description: Enable topics plugin
     type: boolean
     default: no
 
-  # Plugin mode
   plugin_topics_mode:
-    description: Plugin mode
+    description: |
+      Display mode:
+      - `labels`: display labels
+      - `icons`: display icons *(topics without icons will be ignored)*
+      - `starred`: alias for `labels`
+      - `mastered`: alias for `icons`
     type: string
     default: starred
     values:
-      - starred  # Display starred topics as labels
-      - icons    # Display starred topics as icons
-      - mastered # Display starred topics as mastered/known technologies icons
+      - labels
+      - icons
+      - starred
+      - mastered
 
-  # Topics sorting order
   plugin_topics_sort:
-    description: Sorting method of starred topics
+    description: |
+      Sorting method:
+      - `stars`: sort by most stars
+      - `activity`: sort by recent activity
+      - `starred`: sort by the date you starred them
+      - `random`: sort topics randomly
     type: string
     default: stars
     values:
-      - stars    # Sort topics by stargazers
-      - activity # Sort topics by recent activity
-      - starred  # Sort topics by the date you starred them
-      - random   # Sort topics randomly
+      - stars
+      - activity
+      - starred
+      - random
 
-  # Number of topics to display
-  # Set to 0 to disable limitations
-  # When in "starred" mode, additional topics will be grouped into an ellipsis
   plugin_topics_limit:
-    description: Maximum number of topics to display
+    description: |
+      Display limit
+
+      When using `plugin_topics_mode: labels`, an ellipsis will be displayed
     type: number
     default: 15
     min: 0
-    max: 20
+    max: 20
+    zero: disable
diff --git a/source/templates/classic/partials/topics.ejs b/source/templates/classic/partials/topics.ejs
@@ -2,7 +2,7 @@
     <section>
       <h2 class="field">
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path fill-rule="evenodd" d="M14.184 1.143a1.75 1.75 0 00-2.502-.57L.912 7.916a1.75 1.75 0 00-.53 2.32l.447.775a1.75 1.75 0 002.275.702l11.745-5.656a1.75 1.75 0 00.757-2.451l-1.422-2.464zm-1.657.669a.25.25 0 01.358.081l1.422 2.464a.25.25 0 01-.108.35l-2.016.97-1.505-2.605 1.85-1.26zM9.436 3.92l1.391 2.41-5.42 2.61-.942-1.63 4.97-3.39zM3.222 8.157l-1.466 1a.25.25 0 00-.075.33l.447.775a.25.25 0 00.325.1l1.598-.769-.83-1.436zm6.253 2.306a.75.75 0 00-.944-.252l-1.809.87a.75.75 0 00-.293.253L4.38 14.326a.75.75 0 101.238.848l1.881-2.75v2.826a.75.75 0 001.5 0v-2.826l1.881 2.75a.75.75 0 001.238-.848l-2.644-3.863z"></path></svg>
-        <%= {starred:"Starred topics", icons:"Starred topics", mastered:"Mastered technologies and topics"}[plugins.topics.mode] %>
+        <%= {starred:"Starred topics", labels:"Starred topics", icons:"Starred topics", mastered:"Mastered technologies and topics"}[plugins.topics.mode] %>
       </h2>
       <div class="row">
         <% if (plugins.topics.error) { %>
@@ -15,11 +15,11 @@
         <% } else { %>
             <section>
               <div class="topics fill-width">
-                <% if (plugins.topics.mode === "starred") { %>
+                <% if (plugins.topics.type === "labels") { %>
                   <% for (const {name, description} of plugins.topics.list) { %>
                     <div class="label" title="<%= description %>"><%= name.toLocaleLowerCase() %></div>
                   <% } %>
-                <% } else if ((plugins.topics.mode === "mastered")||(plugins.topics.mode === "icons")) { %>
+                <% } else if ((plugins.topics.type === "icons")) { %>
                   <% for (const {name, icon} of plugins.topics.list) { %>
                     <% if (icon) { %>
                       <img src="<%= icon %>" width="24" height="24" alt="<%= name %>" title="<%= name %>"/>
