@openvoxproject/voxblocks 0.14.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openvoxproject/voxblocks",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Web components for OpenVox community web sites and apps",
   "type": "module",
   "license": "Apache-2.0",

package/src/components/code-block/languages.ts

@@ -0,0 +1,259 @@
+/**
+ * A small, dependency-free syntax tokenizer. It trades completeness for
+ * being self-contained (no Prism/highlight.js/Shiki) and covers the
+ * languages that actually show up in OpenVox docs: shell, Puppet
+ * manifests, Hiera/YAML data, JSON, Ruby, plus the web basics.
+ *
+ * Each language is an ordered list of rules; the first rule whose regex
+ * matches at the current position wins, so more specific rules (e.g. "a
+ * quoted key before a colon") must be listed before the general-purpose
+ * ones they'd otherwise be shadowed by.
+ */
+
+export type TokenType =
+  | 'plain'
+  | 'comment'
+  | 'keyword'
+  | 'string'
+  | 'number'
+  | 'function'
+  | 'property'
+  | 'tag';
+
+export interface Token {
+  type: TokenType;
+  text: string;
+}
+
+type TypeResolver = (matchText: string, code: string, matchEnd: number) => TokenType;
+
+interface Rule {
+  re: RegExp;
+  type: TokenType | TypeResolver;
+}
+
+function skipInlineSpace(code: string, from: number): number {
+  let j = from;
+  while (j < code.length && (code[j] === ' ' || code[j] === '\t')) j++;
+  return j;
+}
+
+/** Matches an identifier; resolves to `keyword` if it's in `keywords`, `function` if followed by `(`, else `plain`. */
+function identifierRule(re: RegExp, keywords: Set<string>): Rule {
+  return {
+    re,
+    type: (text, code, end) => {
+      if (keywords.has(text)) return 'keyword';
+      return code[skipInlineSpace(code, end)] === '(' ? 'function' : 'plain';
+    },
+  };
+}
+
+/** Matches a quoted string; resolves to `property` if it's a key (followed by `:`), else `string`. */
+function quotedPropertyRule(re: RegExp): Rule {
+  return {
+    re,
+    type: (_text, code, end) => (code[skipInlineSpace(code, end)] === ':' ? 'property' : 'string'),
+  };
+}
+
+const NUMBER = /-?\b\d+\.?\d*(?:[eE][+-]?\d+)?\b/y;
+const DQ_STRING = /"(?:\\.|[^"\\])*"/y;
+const SQ_STRING = /'(?:\\.|[^'\\])*'/y;
+const HASH_COMMENT = /#.*/y;
+const SLASH_COMMENT = /\/\/.*/y;
+const BLOCK_COMMENT = /\/\*[\s\S]*?\*\//y;
+
+function pushToken(tokens: Token[], type: TokenType, text: string): void {
+  const last = tokens[tokens.length - 1];
+  if (last && last.type === type) {
+    last.text += text;
+  } else {
+    tokens.push({ type, text });
+  }
+}
+
+/** Runs `rules` over `code`, falling back to a single plain-text token for anything unmatched. */
+export function tokenize(code: string, rules: Rule[]): Token[] {
+  const tokens: Token[] = [];
+  let i = 0;
+  while (i < code.length) {
+    let matched = false;
+    for (const rule of rules) {
+      rule.re.lastIndex = i;
+      const m = rule.re.exec(code);
+      if (m && m.index === i && m[0].length > 0) {
+        const text = m[0];
+        const type = typeof rule.type === 'function' ? rule.type(text, code, i + text.length) : rule.type;
+        pushToken(tokens, type, text);
+        i += text.length;
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) {
+      pushToken(tokens, 'plain', code[i]);
+      i++;
+    }
+  }
+  return tokens;
+}
+
+const BASH_KEYWORDS = new Set([
+  'if', 'then', 'elif', 'else', 'fi', 'for', 'while', 'until', 'do', 'done',
+  'case', 'esac', 'in', 'function', 'select', 'time', 'return', 'exit',
+  'break', 'continue', 'local', 'export', 'readonly', 'declare', 'unset',
+  'shift', 'eval', 'exec', 'trap', 'set', 'source', 'alias', 'unalias', 'true', 'false',
+]);
+
+const bash: Rule[] = [
+  { re: HASH_COMMENT, type: 'comment' },
+  { re: /\$\{[^}]*\}|\$[A-Za-z_]\w*|\$[0-9@#?$!*_-]/y, type: 'function' },
+  { re: DQ_STRING, type: 'string' },
+  { re: SQ_STRING, type: 'string' },
+  { re: NUMBER, type: 'number' },
+  identifierRule(/[A-Za-z_][\w-]*/y, BASH_KEYWORDS),
+];
+
+const YAML_KEYWORDS = new Set([
+  'true', 'false', 'yes', 'no', 'null', 'on', 'off',
+  'True', 'False', 'Yes', 'No', 'Null', 'On', 'Off',
+  'TRUE', 'FALSE', 'YES', 'NO', 'NULL', 'ON', 'OFF',
+]);
+
+const yaml: Rule[] = [
+  { re: HASH_COMMENT, type: 'comment' },
+  quotedPropertyRule(DQ_STRING),
+  quotedPropertyRule(SQ_STRING),
+  { re: /[A-Za-z_][\w .-]*?(?=:(\s|$))/y, type: 'property' },
+  { re: /[&*!][A-Za-z_][\w:.]*/y, type: 'function' },
+  { re: NUMBER, type: 'number' },
+  identifierRule(/[A-Za-z_][\w-]*/y, YAML_KEYWORDS),
+];
+
+const json: Rule[] = [
+  quotedPropertyRule(DQ_STRING),
+  { re: NUMBER, type: 'number' },
+  identifierRule(/[A-Za-z_]\w*/y, new Set(['true', 'false', 'null'])),
+];
+
+const JS_KEYWORDS = new Set([
+  'const', 'let', 'var', 'function', 'return', 'if', 'else', 'for', 'while',
+  'do', 'switch', 'case', 'default', 'break', 'continue', 'class', 'extends',
+  'super', 'new', 'this', 'import', 'export', 'from', 'as', 'async', 'await',
+  'try', 'catch', 'finally', 'throw', 'typeof', 'instanceof', 'in', 'of',
+  'yield', 'static', 'get', 'set', 'void', 'delete', 'null', 'undefined',
+  'true', 'false', 'public', 'private', 'protected', 'readonly', 'interface',
+  'type', 'enum', 'implements', 'namespace', 'declare', 'abstract', 'keyof',
+  'satisfies',
+]);
+
+const javascript: Rule[] = [
+  { re: SLASH_COMMENT, type: 'comment' },
+  { re: BLOCK_COMMENT, type: 'comment' },
+  { re: DQ_STRING, type: 'string' },
+  { re: SQ_STRING, type: 'string' },
+  { re: /`(?:\\.|[^`\\])*`/y, type: 'string' },
+  { re: /-?\b0[xXbBoO][0-9a-fA-F]+\b|-?\b\d+\.?\d*(?:[eE][+-]?\d+)?\b/y, type: 'number' },
+  identifierRule(/[A-Za-z_$][\w$]*/y, JS_KEYWORDS),
+];
+
+const css: Rule[] = [
+  { re: BLOCK_COMMENT, type: 'comment' },
+  { re: DQ_STRING, type: 'string' },
+  { re: SQ_STRING, type: 'string' },
+  { re: /@[\w-]+/y, type: 'keyword' },
+  { re: /!important/y, type: 'keyword' },
+  { re: /#[0-9a-fA-F]{3,8}\b/y, type: 'number' },
+  { re: /-?\b\d+\.?\d*[a-zA-Z%]*\b/y, type: 'number' },
+  { re: /[a-zA-Z-]+(?=\s*:)/y, type: 'property' },
+  identifierRule(/[a-zA-Z-]+/y, new Set()),
+];
+
+const htmlLang: Rule[] = [
+  { re: /<!--[\s\S]*?-->/y, type: 'comment' },
+  { re: /<\/?[a-zA-Z][\w:-]*/y, type: 'tag' },
+  { re: /[a-zA-Z-][\w-]*(?=\s*=)/y, type: 'property' },
+  { re: DQ_STRING, type: 'string' },
+  { re: SQ_STRING, type: 'string' },
+  { re: /&[\w#]+;/y, type: 'keyword' },
+];
+
+const RUBY_KEYWORDS = new Set([
+  'def', 'end', 'if', 'elsif', 'else', 'unless', 'while', 'until', 'for',
+  'in', 'do', 'class', 'module', 'begin', 'rescue', 'ensure', 'raise',
+  'return', 'yield', 'break', 'next', 'redo', 'retry', 'case', 'when',
+  'then', 'and', 'or', 'not', 'nil', 'true', 'false', 'self', 'super',
+  'require', 'require_relative', 'include', 'extend', 'attr_accessor',
+  'attr_reader', 'attr_writer', 'private', 'protected', 'public', 'lambda',
+  'proc', 'new',
+]);
+
+const ruby: Rule[] = [
+  { re: HASH_COMMENT, type: 'comment' },
+  { re: /:[A-Za-z_]\w*[?!]?/y, type: 'string' },
+  { re: /@{1,2}[A-Za-z_]\w*|\$[A-Za-z_]\w*/y, type: 'function' },
+  { re: DQ_STRING, type: 'string' },
+  { re: SQ_STRING, type: 'string' },
+  { re: NUMBER, type: 'number' },
+  { re: /[A-Z]\w*/y, type: 'property' },
+  identifierRule(/[a-z_]\w*[?!]?/y, RUBY_KEYWORDS),
+];
+
+const PUPPET_KEYWORDS = new Set([
+  'class', 'define', 'node', 'inherits', 'if', 'elsif', 'else', 'unless',
+  'case', 'and', 'or', 'in', 'undef', 'true', 'false', 'default', 'import',
+  'include', 'require', 'contain', 'function', 'type', 'application',
+  'produces', 'consumes', 'private', 'return', 'break', 'next', 'each',
+  'map', 'filter', 'reduce', 'with',
+  'String', 'Integer', 'Boolean', 'Array', 'Hash', 'Optional', 'Enum',
+  'Variant', 'Numeric', 'Float', 'Undef', 'Any', 'Pattern', 'Regexp',
+  'Sensitive', 'Struct', 'Tuple', 'Type', 'Callable', 'Data', 'Scalar',
+]);
+
+const puppet: Rule[] = [
+  { re: HASH_COMMENT, type: 'comment' },
+  { re: DQ_STRING, type: 'string' },
+  { re: SQ_STRING, type: 'string' },
+  { re: /\$[\w:]+/y, type: 'function' },
+  { re: /[a-zA-Z_][\w:]*(?=\s*\{)/y, type: 'tag' },
+  { re: /[a-z_]\w*(?=\s*=>)/y, type: 'property' },
+  { re: NUMBER, type: 'number' },
+  identifierRule(/[A-Za-z_][\w:]*/y, PUPPET_KEYWORDS),
+];
+
+const GRAMMARS: Record<string, Rule[]> = {
+  bash, sh: bash, shell: bash, zsh: bash,
+  yaml, yml: yaml,
+  json,
+  javascript, js: javascript,
+  typescript: javascript, ts: javascript,
+  css,
+  html: htmlLang, xml: htmlLang,
+  ruby, rb: ruby,
+  puppet, pp: puppet,
+};
+
+export const LANGUAGE_LABELS: Record<string, string> = {
+  bash: 'Bash', sh: 'Shell', shell: 'Shell', zsh: 'Zsh',
+  yaml: 'YAML', yml: 'YAML',
+  json: 'JSON',
+  javascript: 'JavaScript', js: 'JavaScript',
+  typescript: 'TypeScript', ts: 'TypeScript',
+  css: 'CSS',
+  html: 'HTML', xml: 'XML',
+  ruby: 'Ruby', rb: 'Ruby',
+  puppet: 'Puppet', pp: 'Puppet',
+  plaintext: 'Plain Text', text: 'Plain Text',
+};
+
+export type CodeBlockLanguage =
+  | 'plaintext' | 'bash' | 'sh' | 'shell' | 'zsh' | 'yaml' | 'yml' | 'json'
+  | 'javascript' | 'js' | 'typescript' | 'ts' | 'css' | 'html' | 'xml'
+  | 'ruby' | 'rb' | 'puppet' | 'pp';
+
+/** Tokenizes `code` for `language`; unrecognized languages render as plain, unhighlighted text. */
+export function highlight(code: string, language: string): Token[] {
+  const rules = GRAMMARS[language];
+  return rules ? tokenize(code, rules) : [{ type: 'plain', text: code }];
+}

package/src/components/code-block/vox-code-block.ts

@@ -0,0 +1,302 @@
+import { LitElement, html, css, nothing } from 'lit';
+import { customElement, property, state } from 'lit/decorators.js';
+import { ICON_PATHS } from '../icon/icon-paths.js';
+import { highlight, LANGUAGE_LABELS, type Token } from './languages.js';
+
+export type { CodeBlockLanguage } from './languages.js';
+
+/** Strips a shared leading indent and surrounding blank lines, so authored (and thus HTML-indented) code renders flush left. */
+function dedent(text: string): string {
+  const lines = text.split('\n');
+  while (lines.length && lines[0].trim() === '') lines.shift();
+  while (lines.length && lines[lines.length - 1].trim() === '') lines.pop();
+  const indents = lines.filter((l) => l.trim() !== '').map((l) => l.match(/^[ \t]*/)?.[0].length ?? 0);
+  const minIndent = indents.length ? Math.min(...indents) : 0;
+  return lines.map((l) => l.slice(minIndent)).join('\n');
+}
+
+/** Splits tokens on embedded newlines into one array of tokens per source line. */
+function toLines(tokens: Token[]): Token[][] {
+  const lines: Token[][] = [[]];
+  for (const token of tokens) {
+    token.text.split('\n').forEach((part, i) => {
+      if (i > 0) lines.push([]);
+      if (part) lines[lines.length - 1].push({ type: token.type, text: part });
+    });
+  }
+  return lines;
+}
+
+/**
+ * A syntax-highlighted code block with a copy button, no external
+ * highlighter required. Covers shell, Puppet, YAML, JSON, Ruby, JS/TS,
+ * CSS, and HTML; unrecognized languages render as plain text.
+ *
+ * @slot - The code, as plain text (escape `<` and `&` as you would in
+ * any HTML source, e.g. inside a `<code>` child).
+ */
+@customElement('vox-code-block')
+export class VoxCodeBlock extends LitElement {
+  @property() language = '';
+
+  /** Shown in the header instead of/alongside the language label. */
+  @property() filename = '';
+
+  @property({ type: Boolean, attribute: 'line-numbers', reflect: true }) lineNumbers = false;
+
+  @property({ type: Boolean, attribute: 'no-copy' }) noCopy = false;
+
+  /** Hides the whole header bar (filename, language label, and copy button) — for dense contexts like a table cell. */
+  @property({ type: Boolean, attribute: 'no-header' }) noHeader = false;
+
+  /** Drops the outer border — for dropping into a surface (e.g. a table cell) that already has its own edge. */
+  @property({ type: Boolean, attribute: 'no-border', reflect: true }) noBorder = false;
+
+  @state() private _code = '';
+  @state() private _copied = false;
+
+  private _copyResetTimer?: ReturnType<typeof setTimeout>;
+
+  static styles = css`
+    :host {
+      display: block;
+      font-family: var(--vox-font-family-base);
+    }
+
+    .block {
+      border: 1px solid var(--vox-color-border);
+      border-radius: var(--vox-radius-md);
+      background-color: var(--vox-color-bg-alt);
+      overflow: hidden;
+    }
+
+    :host([no-border]) .block {
+      border: none;
+    }
+
+    .header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: var(--vox-space-3);
+      padding: var(--vox-space-2) var(--vox-space-2) var(--vox-space-2) var(--vox-space-4);
+      border-bottom: 1px solid var(--vox-color-divider);
+      font-size: 12px;
+    }
+
+    .meta {
+      display: flex;
+      align-items: baseline;
+      gap: var(--vox-space-3);
+      min-width: 0;
+      overflow: hidden;
+      color: var(--vox-color-text-2);
+    }
+
+    .filename {
+      color: var(--vox-color-text-1);
+      font-family: var(--vox-font-family-mono);
+      font-weight: 600;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+
+    .lang {
+      flex: none;
+      text-transform: uppercase;
+      letter-spacing: 0.04em;
+    }
+
+    .copy {
+      flex: none;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: 28px;
+      height: 28px;
+      padding: 0;
+      border: none;
+      border-radius: var(--vox-radius-sm);
+      background: none;
+      color: var(--vox-color-text-2);
+      cursor: pointer;
+    }
+
+    .copy:hover {
+      background-color: var(--vox-color-brand-soft);
+      color: var(--vox-color-brand-1);
+    }
+
+    .copy:focus-visible {
+      outline: 2px solid var(--vox-color-brand-1);
+      outline-offset: 2px;
+    }
+
+    .copy svg {
+      width: 15px;
+      height: 15px;
+    }
+
+    pre {
+      margin: 0;
+      padding: var(--vox-space-4);
+      overflow-x: auto;
+      white-space: pre;
+      tab-size: 2;
+    }
+
+    pre:focus-visible {
+      outline: 2px solid var(--vox-color-brand-1);
+      outline-offset: -2px;
+    }
+
+    code {
+      font-family: var(--vox-font-family-mono);
+      font-size: 13px;
+      line-height: 1.7;
+      color: var(--vox-color-text-1);
+    }
+
+    .line {
+      display: block;
+    }
+
+    :host([line-numbers]) code {
+      counter-reset: line;
+    }
+
+    :host([line-numbers]) .line {
+      padding-left: 3.5ch;
+      position: relative;
+    }
+
+    :host([line-numbers]) .line::before {
+      counter-increment: line;
+      content: counter(line);
+      position: absolute;
+      left: 0;
+      width: 2.5ch;
+      text-align: right;
+      color: var(--vox-color-text-3);
+      user-select: none;
+    }
+
+    .tok-comment {
+      color: var(--vox-code-comment);
+      font-style: italic;
+    }
+    .tok-keyword {
+      color: var(--vox-code-keyword);
+    }
+    .tok-string {
+      color: var(--vox-code-string);
+    }
+    .tok-number {
+      color: var(--vox-code-number);
+    }
+    .tok-function {
+      color: var(--vox-code-function);
+    }
+    .tok-property {
+      color: var(--vox-code-property);
+    }
+    .tok-tag {
+      color: var(--vox-code-tag);
+    }
+
+    slot {
+      display: none;
+    }
+
+    .visually-hidden {
+      position: absolute;
+      width: 1px;
+      height: 1px;
+      overflow: hidden;
+      clip: rect(0 0 0 0);
+      white-space: nowrap;
+    }
+  `;
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    clearTimeout(this._copyResetTimer);
+  }
+
+  private _handleSlotChange(event: Event) {
+    const slot = event.target as HTMLSlotElement;
+    const text = slot
+      .assignedNodes({ flatten: true })
+      .map((node) => node.textContent ?? '')
+      .join('');
+    this._code = dedent(text);
+  }
+
+  private async _copy() {
+    try {
+      await navigator.clipboard.writeText(this._code);
+    } catch {
+      const textarea = document.createElement('textarea');
+      textarea.value = this._code;
+      textarea.style.position = 'fixed';
+      textarea.style.opacity = '0';
+      this.shadowRoot?.appendChild(textarea);
+      textarea.select();
+      document.execCommand('copy');
+      textarea.remove();
+    }
+    this._copied = true;
+    clearTimeout(this._copyResetTimer);
+    this._copyResetTimer = setTimeout(() => {
+      this._copied = false;
+    }, 1500);
+  }
+
+  render() {
+    const label = LANGUAGE_LABELS[this.language] ?? this.language;
+    const lines = toLines(highlight(this._code, this.language));
+
+    return html`
+      <div class="block">
+        ${this.noHeader
+          ? nothing
+          : html`
+              <div class="header">
+                <span class="meta">
+                  ${this.filename ? html`<span class="filename">${this.filename}</span>` : nothing}
+                  ${label ? html`<span class="lang">${label}</span>` : nothing}
+                </span>
+                ${this.noCopy
+                  ? nothing
+                  : html`
+                      <button
+                        class="copy"
+                        type="button"
+                        @click=${this._copy}
+                        aria-label=${this._copied ? 'Copied' : 'Copy code'}
+                      >
+                        <svg viewBox="0 0 48 48" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                          ${ICON_PATHS[this._copied ? 'check' : 'copy']}
+                        </svg>
+                      </button>
+                    `}
+              </div>
+            `}
+        <pre tabindex="0"><code>${lines.map(
+          (line) => html`<span class="line">${line.map((token) =>
+            token.type === 'plain' ? token.text : html`<span class="tok-${token.type}">${token.text}</span>`,
+          )}</span>`,
+        )}</code></pre>
+        <span class="visually-hidden" aria-live="polite">${this._copied ? 'Copied to clipboard' : ''}</span>
+      </div>
+      <slot @slotchange=${this._handleSlotChange}></slot>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'vox-code-block': VoxCodeBlock;
+  }
+}