termcard 0.0.0-stage → 0.2.0

package/src/tui/actions.js

@@ -0,0 +1,88 @@
+/**
+ * Menu entries. Each entry is { id, icon, label, hint, run }, where `run` resolves to
+ * an outcome: { status, ok } | { view } | { quit: true }.
+ * Entries whose data is missing (e.g. "contact" without an email) are skipped.
+ *
+ * This module has no Node-only imports (the web builder uses it for previews);
+ * operating-system access is passed in as `sys` (see ../system.js).
+ */
+
+import { localize, slugify } from '../text.js';
+import { createVCard } from '../vcard.js';
+import { iconFor } from '../render/icons.js';
+
+const unavailable = async () => false;
+const offline = { openExternal: unavailable, copyToClipboard: unavailable, writeTempFile: () => { throw new Error('unavailable'); } };
+
+const host = (url) => new URL(url).host.replace(/^www\./, '');
+
+export function buildMenu(config, lang, t, sys = offline) {
+  const icon = (key, link) => iconFor(config.icons, key, link);
+  const done = (ok, key, value) => ({ ok, status: t(key, { value }) });
+  const browse = (url) => async () =>
+    (await sys.openExternal(url)) ? done(true, 'status.browser') : done(false, 'status.browserFailed', url);
+  const copy = (value) => async () =>
+    (await sys.copyToClipboard(value)) ? done(true, 'status.copied') : done(false, 'status.copyFailed', value);
+
+  const factories = {
+    contact: () =>
+      config.email && {
+        icon: icon('email'),
+        label: t('action.contact'),
+        hint: t('hint.contact'),
+        run: async () =>
+          (await sys.openExternal(`mailto:${config.email}?subject=${encodeURIComponent(t('mail.subject'))}`))
+            ? done(true, 'status.contact')
+            : done(false, 'status.contactFailed', config.email),
+      },
+    save: () => ({
+      icon: icon('save'),
+      label: t('action.save'),
+      hint: t('hint.save'),
+      run: async () => {
+        let file;
+        try {
+          file = sys.writeTempFile(`${slugify(config.name) || 'contact'}.vcf`, createVCard(config, lang));
+        } catch {
+          return done(false, 'status.saveError');
+        }
+        return (await sys.openExternal(file)) ? done(true, 'status.save') : done(false, 'status.saveFailed', file);
+      },
+    }),
+    website: () =>
+      config.website && {
+        icon: icon('website'),
+        label: t('action.website'),
+        hint: t('hint.website', { host: host(config.website) }),
+        run: browse(config.website),
+      },
+    'copy-email': () => config.email && { icon: icon('email'), label: t('action.copyEmail'), hint: t('hint.copyEmail'), run: copy(config.email) },
+    'copy-phone': () => config.phone && { icon: icon('phone'), label: t('action.copyPhone'), hint: t('hint.copyPhone'), run: copy(config.phone) },
+    language: () =>
+      config.language.available.length > 1 && {
+        icon: icon('language'),
+        label: t('action.language'),
+        hint: t('hint.language'),
+        run: async () => ({ view: 'language' }),
+      },
+    exit: () => ({ icon: icon('exit'), label: t('action.exit'), hint: t('hint.exit'), run: async () => ({ quit: true }) }),
+  };
+
+  const linkEntry = (link) => ({
+    id: `link:${link.id}`,
+    icon: icon('link', link),
+    label: t('action.link', { label: link.label }),
+    hint: t('hint.link', { label: link.label, host: host(link.url) }),
+    run: browse(link.url),
+  });
+
+  return config.menu.items.flatMap((item) => {
+    if (typeof item === 'object') {
+      return [{ id: `custom:${item.url}`, icon: icon('link'), label: localize(item.label, lang), hint: localize(item.hint, lang) || t('hint.link', { host: host(item.url) }), run: browse(item.url) }];
+    }
+    if (item === 'links') return config.links.map(linkEntry);
+    if (item.startsWith('link:')) return config.links.filter((l) => l.id === item.slice(5)).map(linkEntry);
+    const entry = factories[item]?.();
+    return entry ? [{ id: item, ...entry }] : [];
+  });
+}

package/src/tui/app.js

@@ -0,0 +1,164 @@
+/** Interactive card: the card itself plus a keyboard-driven menu below it. */
+
+import readline from 'node:readline';
+import { createTranslator, languageName } from '../i18n/index.js';
+import { layoutCard, layoutHeader } from '../render/card.js';
+import { toAnsi, createPainter } from '../render/format.js';
+import { displayWidth, stripAnsi } from '../text.js';
+import { buildMenu } from './actions.js';
+import * as system from '../system.js';
+import { Screen } from './screen.js';
+
+export function runInteractive(config, { lang: initialLang, depth, stdin, stdout }) {
+  const paint = createPainter(config.theme, depth);
+  const screen = new Screen(stdout);
+  const state = { lang: initialLang, view: 'main', index: 0, status: null };
+  let card = [];
+  let cardRows = 0;
+  let t;
+  let menu;
+
+  const load = () => {
+    t = createTranslator(state.lang, config.strings);
+    menu = buildMenu(config, state.lang, t, system);
+    const top = config.card.enabled ? layoutCard(config, state.lang) : layoutHeader(config, state.lang);
+    card = ['', ...toAnsi(top, config.theme, depth).split('\n')];
+  };
+
+  const ruleWidth = () => Math.max(40, ...card.map((l) => displayWidth(stripAnsi(l)) - 2));
+
+  /** Keeps a line of plain text within the terminal width so it never wraps. */
+  const fit = (text) => {
+    const max = (stdout.columns || 80) - 4;
+    if (displayWidth(text) <= max) return text;
+    let out = '';
+    for (const ch of text) {
+      if (displayWidth(out + ch) > max - 1) break;
+      out += ch;
+    }
+    return `${out}…`;
+  };
+
+  const entries = () =>
+    state.view === 'language'
+      ? [
+          ...config.language.available.map((code) => ({
+            label: `${languageName(code, config.strings)}${code === state.lang ? `  ${paint('accent', '✓')}` : ''}`,
+            hint: '',
+            code,
+          })),
+          { label: t('action.back'), hint: t('hint.back'), back: true },
+        ]
+      : menu;
+
+  const menuLines = () => {
+    const list = entries();
+    const current = list[state.index];
+    const iconWidth = Math.max(0, ...list.map((e) => displayWidth(e.icon ?? '')));
+    const keys = [['↑↓', t('keys.navigate')], ['enter', t('keys.select')], ...(state.view === 'language' ? [['esc', t('keys.back')]] : []), ['q', t('keys.quit')]]
+      .map(([key, word]) => `${paint('muted', key)} ${paint('faint', word)}`)
+      .join(paint('faint', '   ·   '));
+    const status = state.status
+      ? `${paint(state.status.ok ? 'accent' : 'muted', state.status.ok ? '✓' : '•')} ${paint('muted', fit(state.status.text))}`
+      : paint('faint', fit(current?.hint ?? ''));
+    return [
+      '',
+      ...list.map((e, i) => {
+        const glyph = iconWidth ? paint('accent', (e.icon ?? '') + ' '.repeat(iconWidth - displayWidth(e.icon ?? '') + 1)) : '';
+        return i === state.index ? `  ${paint('accent', '›')} ${glyph}${paint('strong', e.label)}` : `    ${glyph}${paint('muted', e.label)}`;
+      }),
+      '',
+      `  ${paint('faint', '─'.repeat(ruleWidth()))}`,
+      `  ${status}`,
+      `  ${keys}`,
+    ];
+  };
+
+  const render = () => screen.paint(menuLines());
+
+  /** Switches language and redraws the card in place (or from the top if it no longer fits). */
+  const switchLanguage = (code) => {
+    screen.clear(cardRows);
+    state.lang = code;
+    load();
+    showMain({ ok: true, text: t('status.language') });
+    cardRows = screen.print(card);
+    render();
+  };
+
+  const showMain = (status = null) => {
+    state.view = 'main';
+    state.index = Math.max(0, menu.findIndex((e) => e.id === 'language'));
+    state.status = status;
+  };
+
+  return new Promise((resolve) => {
+    let busy = false;
+    let closed = false;
+
+    const cleanup = () => {
+      stdin.off('keypress', onKey);
+      if (stdin.isTTY) stdin.setRawMode(false);
+      stdin.pause();
+      screen.showCursor();
+    };
+    const quit = () => {
+      if (closed) return;
+      closed = true;
+      screen.clear();
+      stdout.write('\n');
+      cleanup();
+      resolve();
+    };
+
+    const select = async () => {
+      const entry = entries()[state.index];
+      if (state.view === 'language') {
+        if (entry.code && entry.code !== state.lang) return switchLanguage(entry.code);
+        showMain();
+        return render();
+      }
+      busy = true;
+      const outcome = await entry.run();
+      busy = false;
+      if (closed) return;
+      if (outcome.quit) return quit();
+      if (outcome.view) {
+        state.view = outcome.view;
+        state.index = Math.max(0, config.language.available.indexOf(state.lang));
+        state.status = null;
+        return render();
+      }
+      state.status = { ok: outcome.ok, text: outcome.status };
+      render();
+    };
+
+    async function onKey(str, key = {}) {
+      if ((key.ctrl && key.name === 'c') || key.name === 'q') return quit();
+      if (busy) return;
+      const count = entries().length;
+      if (key.name === 'escape' || key.name === 'backspace' || key.name === 'left') {
+        if (state.view === 'main') return key.name === 'escape' ? quit() : undefined;
+        showMain();
+        return render();
+      }
+      if (key.name === 'up' || key.name === 'k') state.index = (state.index - 1 + count) % count;
+      else if (key.name === 'down' || key.name === 'j' || key.name === 'tab') state.index = (state.index + 1) % count;
+      else if (/^[1-9]$/.test(str ?? '') && Number(str) <= count) state.index = Number(str) - 1;
+      else if (key.name === 'return' || key.name === 'space' || key.name === 'right') return select();
+      else return;
+      state.status = null;
+      render();
+    }
+
+    load();
+    readline.emitKeypressEvents(stdin);
+    stdin.setRawMode(true);
+    stdin.resume();
+    screen.hideCursor();
+    process.once('exit', () => screen.showCursor());
+    cardRows = screen.print(card);
+    render();
+    stdin.on('keypress', onKey);
+  });
+}

package/src/tui/screen.js

@@ -0,0 +1,54 @@
+/**
+ * Redraws a block of lines in place below whatever is already on screen,
+ * instead of clearing the terminal (which leaves empty space in some terminals).
+ * Heights are counted in screen rows, so lines that wrap are handled correctly.
+ */
+
+import { displayWidth, stripAnsi } from '../text.js';
+
+/** Number of screen rows `lines` occupy in a terminal `columns` wide. */
+export function rowsFor(lines, columns) {
+  if (!columns) return lines.length;
+  return lines.reduce((rows, line) => rows + Math.max(1, Math.ceil(displayWidth(stripAnsi(line)) / columns)), 0);
+}
+
+export class Screen {
+  constructor(stream) {
+    this.stream = stream;
+    this.height = 0;
+  }
+
+  rows(lines) {
+    return rowsFor(lines, this.stream.columns);
+  }
+
+  /** Writes lines below the current block without replacing it (e.g. the card). */
+  print(lines) {
+    this.stream.write(`${lines.join('\n')}\n`);
+    return this.rows(lines);
+  }
+
+  /** Replaces the previously painted block with `lines`. */
+  paint(lines) {
+    const up = this.height ? `\x1b[${this.height}A` : '';
+    this.stream.write(`${up}\r\x1b[J${lines.join('\n')}\n`);
+    this.height = this.rows(lines);
+  }
+
+  /** Erases the painted block plus `extra` rows above it (or the whole screen if they scrolled away). */
+  clear(extra = 0) {
+    const total = this.height + extra;
+    if (!total) return;
+    const visible = !this.stream.rows || total < this.stream.rows;
+    this.stream.write(visible ? `\x1b[${total}A\r\x1b[J` : '\x1b[2J\x1b[H');
+    this.height = 0;
+  }
+
+  hideCursor() {
+    this.stream.write('\x1b[?25l');
+  }
+
+  showCursor() {
+    this.stream.write('\x1b[?25h');
+  }
+}

package/src/vcard.js

@@ -0,0 +1,28 @@
+/** vCard 3.0 (RFC 2426) export of the card's contact details. */
+
+import { localize } from './text.js';
+
+// Escape per RFC 2426 §5: backslash, comma, semicolon and newlines.
+const esc = (value) => String(value).replace(/\\/g, '\\\\').replace(/,/g, '\\,').replace(/;/g, '\\;').replace(/\r?\n/g, '\\n');
+
+export function createVCard(config, lang) {
+  const words = config.name.split(/\s+/);
+  const family = words.length > 1 ? words.at(-1) : '';
+  const given = words.length > 1 ? words.slice(0, -1).join(' ') : words[0];
+  const lines = [
+    'BEGIN:VCARD',
+    'VERSION:3.0',
+    `N:${esc(family)};${esc(given)};;;`,
+    `FN:${esc(config.name)}`,
+    config.organization && `ORG:${esc(config.organization)}`,
+    config.title && `TITLE:${esc(localize(config.title, lang))}`,
+    config.email && `EMAIL;TYPE=INTERNET:${esc(config.email)}`,
+    config.phone && `TEL;TYPE=CELL:${esc(config.phone)}`,
+    config.website && `URL:${esc(config.website)}`,
+    ...config.links.map((l) => `X-SOCIALPROFILE;TYPE=${esc(l.id)}:${esc(l.url)}`),
+    config.description && `NOTE:${esc(localize(config.description, lang))}`,
+    'END:VCARD',
+    '',
+  ];
+  return lines.filter((l) => l !== undefined && l !== false && l !== null).join('\r\n');
+}