twiddle-panel 0.8.1 → 0.9.0

package/README.md

@@ -18,7 +18,7 @@ Panel used to be published as `@theoldpixel/twiddle`; that package is deprecated
 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.
+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. With a build tool it loads the panel only while developing (the tokens always); add `--always` to keep it in production builds too, for example on shared preview links. For Next.js it prints a small client component to use instead.
 
 **Projects with a build tool (Vite, Next.js…)**
 
@@ -43,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.8.1/dist/twiddle.js" defer></script>
+<script src="https://cdn.jsdelivr.net/npm/twiddle-panel@0.9.0/dist/twiddle.js" defer></script>
 ```
 
 The prototype's CSS must use the `--twd-*` token variables
@@ -63,13 +63,13 @@ that use them can be re-pointed in **Spacing › Layout roles**.
 
 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".
+- **Tabs** along the top: **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, fill and borders) and **Shadows**. Tabs stay in step: when the Character pad changes something another tab owns (corners, borders, shadows, weights), that tab shows the real value and says "from Character". Each tab ends with its tokens as rows you can set to a fixed value; an edited token shows **Custom** and its own reset. One row along the bottom holds every action (Undo, Redo, Pick, Compare, Copy link, Reset, Changes, Copy prompt); the Panel button opens and closes the panel. **Copy link** shares the exact version (`?twd=…`).
+- **Pick** (arrow) starts selection mode: click an element and every tab now changes just that element (Character pad included), until you press **Pick** again. 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.
-- **Minimise** (line) shrinks the panel to just its tabs, beside the Panel button; click a tab to open it again.
+- **Minimise** (the chevron at the end of the tabs) shrinks the panel to just its tabs, beside the Panel button; click a tab or the chevron 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.
+- **Undo / Redo** in the bottom row, or ⌘Z / ⇧⌘Z while the panel has focus. Reset can be undone too.
+- **Changes** (the number in a circle, bottom row) opens a side panel next to the main one, listing every tweak with the token values before and after. Use × on a row to remove it.
 - **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

@@ -7,8 +7,10 @@
 
      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 --always     build tools: load the panel in every
+                                         build, e.g. for shared preview links
+                                         (default: development only, tokens
+                                         always)
      npx twiddle-panel init --file <path>   use this entry / HTML file
    --------------------------------------------------------- */
 
@@ -20,7 +22,6 @@ 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);
@@ -34,13 +35,17 @@ 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}`);
+  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 --always     load the panel in every build (shared previews)\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 } : {};
+// Development only (the default for build tools). import.meta.env.DEV exists only
+// in Vite; other bundlers (webpack, Create React App…) replace process.env.NODE_ENV.
+const devCheck = deps.vite ? 'import.meta.env.DEV' : "process.env.NODE_ENV !== 'production'";
+const IMPORT_DEV = `import '${NAME}/tokens.css';\nif (${devCheck}) import('${NAME}');`;
 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">). */
@@ -81,13 +86,14 @@ if (plan.kind === 'next') {
 }
 
 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}`);
+  say(`Couldn't find an entry file or index.html here.\n\nWith a build tool, add this to your app's entry file (the panel loads only while developing):\n${indent(IMPORT_DEV)}\n  (In a Vite project, use: if (import.meta.env.DEV) import('${NAME}');)\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);
+// --dev-only (0.8.0/0.8.1) is now the default and still accepted.
+const lines = plan.kind === 'html' ? SCRIPT_TAG : (flag('--always') ? IMPORT : IMPORT_DEV);
 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')) {
@@ -98,7 +104,8 @@ if (src.includes(NAME) || src.includes('twiddle.js')) {
 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}`);
+  if (plan.kind === 'build') say(flag('--always') ? 'This loads the panel in every build, including production.\n' : 'This loads the panel only while developing (the tokens always). Add --always to keep it in production builds too, e.g. for shared preview links.\n');
+  say(`Run again with --write to add it for you.\nGuide: ${DOCS}`);
   process.exit(0);
 }
 
@@ -114,5 +121,6 @@ if (plan.kind === 'html') {
 }
 writeFileSync(plan.file, out);
 say(`Added Panel ${where}.`);
+if (plan.kind === 'build' && !flag('--always')) say('It loads only while developing. For shared preview links, use --always instead.');
 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}`);