twiddle-panel 0.7.1 → 0.8.0

package/README.md

@@ -12,6 +12,14 @@ Panel is a design tool: load it in development or in shared prototype links, not
 
 Panel used to be published as `@theoldpixel/twiddle`; that package is deprecated in favour of `twiddle-panel`.
 
+**Quickest: let the setup command find the right file**
+
+```bash
+npx twiddle-panel init
+```
+
+It shows the line to add and where (your entry file, or `index.html` for plain pages), and changes nothing. Add `--write` to add it, `--dev-only` to load the panel only while developing. For Next.js it prints a small client component to use instead.
+
 **Projects with a build tool (Vite, Next.js…)**
 
 ```bash
@@ -35,7 +43,7 @@ if (import.meta.env.DEV) import('twiddle-panel');
 **Plain HTML prototypes** (no install needed)
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/twiddle-panel@0.7.1/dist/twiddle.js" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/twiddle-panel@0.8.0/dist/twiddle.js" defer></script>
 ```
 
 The prototype's CSS must use the `--twd-*` token variables
@@ -49,14 +57,18 @@ Optional component tokens (contract v0.4) let the Shape tab restyle the main but
 Optional layout roles (token contract v0.2) name what a space is for:
 `--twd-page-pad`, `--twd-section-gap`, `--twd-card-pad`, `--twd-card-gap` and
 `--twd-control-gap`. Each points at a spacing step by default, so prototypes
-that use them can be re-pointed in **Edit every token › Spacing › Roles**.
+that use them can be re-pointed in **Spacing › Layout roles**.
 
 ## Using the panel
 
+Open it with the Panel button in the bottom-right corner, or Alt+T (Option+T on a Mac). The panel opens to the left of the button.
+
 - **Tabs** along the bottom: **Overview** (the **Character** pad: up/down for spacing, Subtle ↔ Bold for weights, borders, corners and shadows; plus a summary of the current look), **Colour** (four themes, then fine-tune with the Tailwind palette: a colour family and shade for the primary, a grey family for the neutrals, or any custom hex; Light/Dark), **Type** (font pairings as tiles, base size, scale), **Spacing** (density, layout roles), **Shape** (button style, corners and size; card style, corners and borders) and **Shadows**. Each tab ends with its tokens as rows you can set to a fixed value; an edited token shows **Custom** and its own reset. The header holds the global actions; **Copy link** shares the exact version (`?twd=…`).
 - **Pick** (crosshair) selects one element. The panel then shows only the sections that element uses. Choose **This element** or **All `.class` (n)** to set where the tweaks go. Add `data-twd="name"` to an element to control what counts as "all like this".
 - **Compare** (half circle): hold it, or press Alt+C, to see the original page.
-- **Undo / Redo** in the footer, or ⌘Z / ⇧⌘Z while the panel has focus. Reset can be undone too.
+- **Minimise** (line) shrinks the panel to just its tabs, beside the Panel button; click a tab to open it again.
+- **Move it**: drag the Panel button to any spot; it attaches to the nearest corner, keeps its distance from the edges, and the panel opens on the side away from the edge. With the button focused, arrow keys nudge it 1px (Shift: 10px). Double-click it to put it back bottom-right. Remembered for the site in this browser.
+- **Undo / Redo** in the header, or ⌘Z / ⇧⌘Z while the panel has focus. Reset can be undone too.
 - **Changes** lists every tweak with the token values before and after. Use × to remove one.
 - **Copy prompt** turns the tweaks into a Markdown prompt for a coding agent, so they become permanent in the source. Use the arrow next to it to choose between *Preview before copying* and *Copy without preview*.
 - Colour pairs that fall below WCAG AA show a warning in Colour, in Changes and in the prompt.

package/bin/init.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+/* ---------------------------------------------------------
+   npx twiddle-panel init — optional setup helper (TODO: "Later").
+
+   Finds where Panel should load and shows the line to add.
+   Changes nothing unless --write is passed; never adds a line twice.
+
+     npx twiddle-panel init              show what to add, and where
+     npx twiddle-panel init --write      add it
+     npx twiddle-panel init --dev-only   build tools: load the panel only
+                                         in development (tokens always)
+     npx twiddle-panel init --file <path>   use this entry / HTML file
+   --------------------------------------------------------- */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const pkgSelf = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const NAME = pkgSelf.name;
+const VERSION = pkgSelf.version;
+const SCRIPT_TAG = `<script src="https://cdn.jsdelivr.net/npm/${NAME}@${VERSION}/dist/twiddle.js" defer></script>`;
+const IMPORT = `import '${NAME}';`;
+const IMPORT_DEV = `import '${NAME}/tokens.css';\nif (import.meta.env.DEV) import('${NAME}');`;
+const DOCS = 'https://panel.twiddle.in';
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const flag = (f) => args.includes(f);
+const fileArg = args.includes('--file') ? args[args.indexOf('--file') + 1] : null;
+const cwd = process.cwd();
+const rel = (p) => relative(cwd, p) || p;
+
+const say = (s = '') => process.stdout.write(`${s}\n`);
+const indent = (s) => s.split('\n').map((l) => `    ${l}`).join('\n');
+
+if (cmd !== 'init') {
+  say(`Panel by Twiddle ${VERSION}\n\nUsage:\n  npx ${NAME} init              show the line to add, and where\n  npx ${NAME} init --write      add it\n  npx ${NAME} init --dev-only   load the panel only in development\n  npx ${NAME} init --file <path>  use this entry or HTML file\n\nGuide: ${DOCS}`);
+  process.exit(cmd && !['help', '--help', '-h'].includes(cmd) ? 1 : 0);
+}
+
+const readJSON = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch (e) { return null; } };
+const pkg = readJSON(join(cwd, 'package.json'));
+const deps = pkg ? { ...pkg.dependencies, ...pkg.devDependencies } : {};
+const first = (list) => list.map((p) => join(cwd, p)).find((p) => existsSync(p)) || null;
+
+/** The JS file a Vite-style index.html loads (<script type="module" src="/src/main.ts">). */
+function moduleEntry(htmlPath) {
+  const m = /<script[^>]*type=["']module["'][^>]*src=["']\/?([^"']+)["']/i.exec(readFileSync(htmlPath, 'utf8'))
+    || /<script[^>]*src=["']\/?([^"']+)["'][^>]*type=["']module["']/i.exec(readFileSync(htmlPath, 'utf8'));
+  if (!m || /^https?:/.test(m[1])) return null;
+  const p = join(cwd, m[1]);
+  return existsSync(p) ? p : null;
+}
+
+// ---- Work out the kind of project and the file to change ----
+let plan;
+if (deps.next) {
+  plan = { kind: 'next' };
+} else if (fileArg) {
+  const p = join(cwd, fileArg);
+  if (!existsSync(p)) { say(`Can't find ${fileArg}.`); process.exit(1); }
+  plan = /\.html?$/i.test(p) ? { kind: 'html', file: p } : { kind: 'build', file: p };
+} else if (pkg) {
+  const html = first(['index.html']);
+  const file = (html && moduleEntry(html))
+    || first(['src/main.ts', 'src/main.tsx', 'src/main.js', 'src/main.jsx', 'src/index.ts', 'src/index.tsx', 'src/index.js', 'src/index.jsx', 'main.js', 'index.js']);
+  plan = file ? { kind: 'build', file } : (html ? { kind: 'html', file: html } : { kind: 'unknown' });
+} else {
+  const html = first(['index.html']);
+  plan = html ? { kind: 'html', file: html } : { kind: 'unknown' };
+}
+
+// ---- Next.js: the panel needs the browser, so only print guidance ----
+if (plan.kind === 'next') {
+  say(`This looks like a Next.js project. Panel needs the browser, so load it from a client component:\n`);
+  say(indent(`// app/twiddle.tsx\n'use client';\nimport { useEffect } from 'react';\nimport '${NAME}/tokens.css';\nexport default function Twiddle() {\n  useEffect(() => { import('${NAME}'); }, []);\n  return null;\n}`));
+  say(`\nThen render <Twiddle /> once in app/layout.tsx, inside <body>.`);
+  if (!deps[NAME]) say(`\nInstall first:\n    npm install -D ${NAME}`);
+  say(`\nGuide: ${DOCS}`);
+  process.exit(0);
+}
+
+if (plan.kind === 'unknown') {
+  say(`Couldn't find an entry file or index.html here.\n\nWith a build tool, add this to your app's entry file:\n${indent(IMPORT)}\n\nIn a plain HTML page, add this inside <head>:\n${indent(SCRIPT_TAG)}\n\nOr point at a file: npx ${NAME} init --file <path>\nGuide: ${DOCS}`);
+  process.exit(1);
+}
+
+// ---- Show, then (with --write) add ----
+const src = readFileSync(plan.file, 'utf8');
+const lines = plan.kind === 'html' ? SCRIPT_TAG : (flag('--dev-only') ? IMPORT_DEV : IMPORT);
+const where = plan.kind === 'html' ? `inside <head> of ${rel(plan.file)}` : `at the top of ${rel(plan.file)}`;
+
+if (src.includes(NAME) || src.includes('twiddle.js')) {
+  say(`Panel is already loaded in ${rel(plan.file)}. Nothing to do.`);
+  process.exit(0);
+}
+
+if (!flag('--write')) {
+  say(`Add this ${where}:\n\n${indent(lines)}\n`);
+  if (plan.kind === 'build' && !deps[NAME]) say(`Install first:\n    npm install -D ${NAME}\n`);
+  say(`Run again with --write to add it for you.${plan.kind === 'build' && !flag('--dev-only') ? ' Add --dev-only to load the panel only while developing.' : ''}\nGuide: ${DOCS}`);
+  process.exit(0);
+}
+
+let out;
+if (plan.kind === 'html') {
+  if (!/<\/head>/i.test(src)) { say(`${rel(plan.file)} has no </head>. Add this inside <head> yourself:\n${indent(SCRIPT_TAG)}`); process.exit(1); }
+  out = src.replace(/(\s*)<\/head>/i, (m, ws) => `${ws}  ${SCRIPT_TAG}${ws}</head>`);
+} else {
+  // At the top, after a leading 'use client'-style directive if there is one.
+  const directive = /^(\s*(['"])use [a-z]+\2;?\s*\n)/.exec(src);
+  const at = directive ? directive[0].length : 0;
+  out = `${src.slice(0, at)}${lines}\n${src.slice(at)}`;
+}
+writeFileSync(plan.file, out);
+say(`Added Panel ${where}.`);
+if (plan.kind === 'build' && !deps[NAME]) say(`\nNow install it:\n    npm install -D ${NAME}`);
+say(`\nYour CSS needs the --twd-* tokens for the panel to change anything. Guide and agent prompt: ${DOCS}`);