@single-studio/plugin-sheets 0.6.2 → 0.7.0

package/README.md

@@ -11,7 +11,7 @@ npm i @single-studio/plugin-sheets
 ```js
 import { sheets, GoogleSheetsHandler } from '@single-studio/plugin-sheets'
 
-// Which sheet, and which cells, are the *studio's* — see below.
+// The range is yours. The id is a default the operator may replace — see below.
 const SHEET = { id: '1AbC…', range: 'Standings!A1:D20' }
 
 class MyShow extends GoogleSheetsHandler {
@@ -28,14 +28,23 @@ your graphics as `teamName`.
 
 ## What the operator sets, and what you set
 
-The operator's board asks for **an API key** and **how often to read**. That is
-deliberately all of it.
+The operator's board asks for **which sheet**, **an API key** and **how often to
+read**.
 
-The **spreadsheet id and range are yours**, passed to the factory. A range is not a
-preference: your graphics have code expecting columns in an order, and a range that
-does not match does not show a different view of the same data — it shows the wrong
-column, confidently, with no error anywhere. Both are also already decided by the time
-anyone opens the panel, so offering them is offering a choice that has been made.
+The **range is yours** and cannot be overridden. A range is not a preference: your
+graphics have code expecting columns in an order, and a range that does not match does
+not show a different view of the same data — it shows the wrong column, confidently,
+with no error anywhere.
+
+The **id is a default the operator may replace**. That is a different question from
+the range, and it took a broadcaster asking to see why: the range is the _shape_ of a
+sheet, the id is _which copy of that shape_. A team running two setups off duplicates
+of one layout needs each pointed at its own, and the graphics cannot tell the
+difference — which is exactly what makes it safe where a range is not.
+
+Leaving the field blank uses the id you shipped, so changing it in a later release
+reaches everyone who never overrode it. An operator may paste the sheet's whole
+address rather than its id; that works, because it is what people actually copy.
 
 ## The key
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@single-studio/plugin-sheets",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Google Sheets for Single Studio: a shared spreadsheet as a data source, with an API key and no backend.",
   "license": "MIT",
   "author": {
@@ -33,7 +33,7 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@single-studio/core": "^0.6.0"
+    "@single-studio/core": "^0.7.0"
   },
   "devDependencies": {
     "@single-studio/core": "workspace:*",

package/src/index.js

@@ -1,6 +1,6 @@
 import { definePlugin, PluginHandler, PollingService } from '@single-studio/core/worker'
 
-import { explain, parse, urlFor } from './sheet.js'
+import { explain, idFrom, parse, urlFor } from './sheet.js'
 
 export { explain, keyOf, parse, same, urlFor } from './sheet.js'
 
@@ -82,16 +82,22 @@ export class GoogleSheetsHandler extends PluginHandler {
 /**
  * @param {typeof GoogleSheetsHandler} [Handler]
  * @param {{ id?: string, range?: string, header?: boolean }} [sheet]
- *   Which spreadsheet, and which cells. **Given by the studio, not by the operator.**
+ *   The sheet this studio was written against: which spreadsheet, and which cells.
  *
- *   A range is not a preference. The studio reading it has code that expects columns
- *   in an order, and a range that does not match is not a different view of the same
- *   data -- it is a graphic quietly showing the wrong column, which is the worst way
- *   for this to fail. The same goes for the id: a studio ships knowing the shape of
- *   the sheet it was written against.
+ *   **The range is the studio's and cannot be overridden.** It is not a preference.
+ *   The graphics reading it have code that expects columns in an order, and a range
+ *   that does not match is not a different view of the same data -- it is a graphic
+ *   quietly showing the wrong column, which is the worst way for this to fail.
  *
- *   So the operator is asked for the one thing that is genuinely theirs and cannot
- *   be shipped -- an API key, which is a credential.
+ *   **The id is a default the operator may replace**, which is a different question
+ *   from the range and was once wrongly treated as the same one. The range is the
+ *   *shape* of a sheet; the id is *which copy of that shape*. A team running two
+ *   setups off duplicates of one layout needs to point each at its own, and the
+ *   graphics cannot tell the difference -- that is what makes it safe where a range
+ *   is not.
+ *
+ *   Leave the field on the panel blank and the studio's id is used, so a studio that
+ *   ships a new sheet in a later release reaches everybody who never overrode it.
  */
 export const sheets = (Handler = GoogleSheetsHandler, sheet = {}) =>
   definePlugin({
@@ -110,7 +116,7 @@ export const sheets = (Handler = GoogleSheetsHandler, sheet = {}) =>
       },
       {
         type: 'note',
-        text: 'Which sheet this reads, and which cells, come from the studio rather than from here. They have to match the graphics that read them, so they are not something to change during a show.',
+        text: 'Which cells this reads comes from the studio and cannot be changed here — the graphics expect those columns in that order. Which sheet it reads can: leave Spreadsheet blank for the one the studio ships, or paste another that uses the same layout.',
       },
       { type: 'link', href: 'https://console.cloud.google.com/apis/credentials', label: 'Google Cloud credentials' },
       {
@@ -120,6 +126,17 @@ export const sheets = (Handler = GoogleSheetsHandler, sheet = {}) =>
       { type: 'text', text: 'The first row is used as column names by default, so a heading of "Team Name" becomes teamName in your graphics.' },
     ],
     config: [
+      {
+        key: 'id',
+        label: 'Spreadsheet',
+        type: 'text',
+        // The studio's own id, greyed out rather than filled in. Filling it in would
+        // store it, and a stored copy is a copy that stops following the studio --
+        // a later release pointing at a new sheet would reach nobody who had ever
+        // opened this panel.
+        placeholder: sheet.id ?? 'The one this studio ships with',
+        help: 'Paste the sheet’s address from your browser, or just its id. Leave it blank to use the sheet this studio ships with.',
+      },
       {
         key: 'key',
         label: 'API key',
@@ -129,9 +146,15 @@ export const sheets = (Handler = GoogleSheetsHandler, sheet = {}) =>
       { key: 'every', label: 'Read every (seconds)', type: 'number', default: 10, help: 'Five is the floor. Google allows sixty reads a minute.' },
     ],
     create: (context) => {
-      // The studio's sheet wins over anything stored, because there is nowhere to
-      // store it from -- these are not fields on the panel.
-      const plugin = new GoogleSheets({ ...context, config: { ...context.config, ...sheet } })
+      // The shape is the studio's and the copy is the operator's. `...sheet` puts the
+      // studio's range and header beyond reach of the panel; the line after it hands
+      // the id back, because that one *is* on the panel now.
+      //
+      // Blank falls through to the studio's rather than being stored as empty, so an
+      // operator who opens the panel to change the read interval does not silently
+      // pin the sheet to whatever it was that day.
+      const chosen = idFrom(context.config?.id) || sheet.id || ''
+      const plugin = new GoogleSheets({ ...context, config: { ...context.config, ...sheet, id: chosen } })
 
       new Handler({ ...context, plugin }).attach(plugin.events)
 

package/src/sheet.js

@@ -92,6 +92,30 @@ export const same = (a, b) => JSON.stringify(a) === JSON.stringify(b)
  * @param {string} options.range A1 notation, e.g. `Standings!A1:D20`.
  * @param {string} options.key
  */
+/**
+ * The spreadsheet id, from whatever somebody pasted.
+ *
+ * Nobody copies the id. They copy the address bar, because that is where the sheet
+ * is -- and a bare id is a 44-character string in the middle of it that has to be
+ * found and trimmed by hand. Pasting the whole URL is the ordinary thing to do, so
+ * it is the thing that has to work; the alternative is a 404 on a show and an
+ * operator with no reason to suspect the field they filled in correctly.
+ *
+ * Anything that is not a Sheets URL is handed back trimmed and used as-is, so a bare
+ * id still works and a typo still reaches Google to be refused with a real message
+ * rather than being second-guessed here.
+ */
+export function idFrom(value) {
+  const text = String(value ?? '').trim()
+
+  if (!text) return ''
+
+  // /spreadsheets/d/<id>/edit#gid=0, and every other tail Google hangs off it.
+  const inUrl = /\/spreadsheets\/d\/([A-Za-z0-9_-]+)/.exec(text)
+
+  return inUrl ? inUrl[1] : text
+}
+
 export function urlFor({ id, range, key }) {
   if (!id) throw new Error('A spreadsheet id is needed.')
   if (!key) throw new Error('A Google API key is needed.')