@stats-forge/github-stats-forge-core 0.0.2 → 0.2.0

package/src/markup/css.ts

@@ -0,0 +1,118 @@
+import type { Sink } from './serialize.ts';
+import { INDENT, indentAt } from './serialize.ts';
+
+/** Every CSS property a card declares, closed so a typo is a compile error, not a dropped rule. */
+type CssProperty =
+  | '-webkit-box-orient'
+  | '-webkit-line-clamp'
+  | 'animation'
+  | 'animation-delay'
+  | 'animation-duration'
+  | 'color'
+  | 'display'
+  | 'fill'
+  | 'font'
+  | 'font-size'
+  | 'font-variant-numeric'
+  | 'font-weight'
+  | 'line-clamp'
+  | 'line-height'
+  | 'margin'
+  | 'opacity'
+  | 'overflow'
+  | 'overflow-wrap'
+  | 'padding-bottom'
+  | 'stroke'
+  | 'stroke-dasharray'
+  | 'stroke-dashoffset'
+  | 'stroke-linecap'
+  | 'stroke-width'
+  | 'text-overflow'
+  | 'transform'
+  | 'transform-origin'
+  | 'width'
+  | 'word-break';
+
+/** A declaration whose value is `undefined` is left out, so a caller can inline a condition. */
+type Declarations = Partial<Record<CssProperty, string | number | undefined>>;
+
+type CssNode =
+  | { readonly kind: 'rule'; readonly selector: string; readonly declarations: Declarations }
+  | { readonly kind: 'at'; readonly prelude: string; readonly children: Array<CssChild> }
+  | { readonly kind: 'comment'; readonly text: string };
+
+/** Anything accepted where CSS is expected; falsy entries drop out, arrays flatten. */
+type CssChild = CssNode | false | null | undefined | Array<CssChild>;
+
+/**
+ * Selectors stay free-form: they compose (`.badge rect`), and a keyframe stop is one too (`from`).
+ */
+const rule = (selector: string, declarations: Declarations): CssNode => ({
+  kind: 'rule',
+  selector,
+  declarations,
+});
+
+const atRule = (prelude: string, ...children: Array<CssChild>): CssNode => ({
+  kind: 'at',
+  prelude,
+  children,
+});
+
+const cssComment = (text: string): CssNode => ({ kind: 'comment', text });
+
+/** Drops the rules that carry nothing and flattens the arrays. */
+const flatten = (children: Array<CssChild>, into: Array<CssNode> = []): Array<CssNode> => {
+  for (const child of children) {
+    if (!child) {
+      continue;
+    }
+    if (Array.isArray(child)) {
+      flatten(child, into);
+    } else {
+      into.push(child);
+    }
+  }
+  return into;
+};
+
+/**
+ * Serializes a stylesheet, dropping every rule that would have come out empty.
+ *
+ * A block is written optimistically and rewound if its body turns out empty,
+ * so the tree is walked once however deeply the at-rules nest.
+ */
+const writeCss = (children: Array<CssChild>, depth: number, sink: Sink): void => {
+  const indent = indentAt(depth);
+
+  for (const node of flatten(children)) {
+    if (node.kind === 'comment') {
+      sink.out += `${indent}/* ${node.text} */\n`;
+      continue;
+    }
+
+    const mark = sink.out.length;
+
+    if (node.kind === 'at') {
+      sink.out += `${indent}${node.prelude} {\n`;
+      const bodyStart = sink.out.length;
+      writeCss(node.children, depth + 1, sink);
+      sink.out =
+        sink.out.length === bodyStart ? sink.out.slice(0, mark) : `${sink.out}${indent}}\n`;
+      continue;
+    }
+
+    sink.out += `${indent}${node.selector} {\n`;
+    const bodyStart = sink.out.length;
+    for (const property of Object.keys(node.declarations) as Array<CssProperty>) {
+      const value = node.declarations[property];
+      if (value !== undefined) {
+        sink.out += `${indent}${INDENT}${property}: ${String(value)};\n`;
+      }
+    }
+    sink.out = sink.out.length === bodyStart ? sink.out.slice(0, mark) : `${sink.out}${indent}}\n`;
+  }
+};
+
+export { atRule, cssComment, rule, writeCss };
+export type { CssChild, Declarations };

package/src/markup/element.ts

@@ -0,0 +1,246 @@
+import type { CssChild } from './css.ts';
+import { writeCss } from './css.ts';
+import { encodeHTML } from './html.ts';
+import type { Sink } from './serialize.ts';
+import { indentAt } from './serialize.ts';
+
+/**
+ * Every element a card draws, closed so `el('circel', …)` is a compile error.
+ * `style` is absent on purpose: it comes from `style()`, which takes rules rather than children.
+ */
+type Tag =
+  | 'a'
+  | 'circle'
+  | 'defs'
+  | 'desc'
+  | 'div'
+  | 'foreignObject'
+  | 'g'
+  | 'linearGradient'
+  | 'mask'
+  | 'path'
+  | 'rect'
+  | 'stop'
+  | 'svg'
+  | 'text'
+  | 'title'
+  | 'tspan';
+
+/**
+ * Every attribute a card writes, closed like `Tag`:
+ * a misspelled `stroke-width` would otherwise be valid TypeScript and invisible in the output.
+ */
+type Attribute =
+  | 'alignment-baseline'
+  | 'aria-hidden'
+  | 'aria-labelledby'
+  | 'class'
+  | 'cx'
+  | 'cy'
+  | 'd'
+  | 'data-testid'
+  | 'data-view-component'
+  | 'dominant-baseline'
+  | 'dy'
+  | 'fill'
+  | 'fill-rule'
+  | 'gradientTransform'
+  | 'gradientUnits'
+  | 'height'
+  | 'href'
+  | 'id'
+  | 'mask'
+  | 'offset'
+  | 'r'
+  | 'role'
+  | 'rx'
+  | 'ry'
+  | 'size'
+  | 'stop-color'
+  | 'stroke'
+  | 'stroke-dasharray'
+  | 'stroke-dashoffset'
+  | 'stroke-linecap'
+  | 'stroke-opacity'
+  | 'stroke-width'
+  | 'style'
+  | 'text-anchor'
+  | 'transform'
+  | 'version'
+  | 'viewBox'
+  | 'width'
+  | 'x'
+  | 'xmlns'
+  | 'y';
+
+/** An attribute whose value is `undefined` is not written, so a caller can inline a condition. */
+type Attributes = Partial<Record<Attribute, string | number | undefined>>;
+
+/** Elements whose character data is part of the rendering, so they stay on one line. */
+const INLINE_ELEMENTS: ReadonlySet<Tag> = new Set(['text', 'tspan', 'title', 'desc', 'div']);
+
+interface MarkupElement {
+  readonly tag: Tag;
+  readonly attributes: Attributes;
+  readonly children: Array<Child>;
+}
+
+interface StyleElement {
+  readonly tag: 'style';
+  readonly rules: Array<CssChild>;
+}
+
+/** Anything accepted as content; falsy entries drop out, arrays flatten, strings are escaped. */
+type Child =
+  | MarkupElement
+  | StyleElement
+  | string
+  | number
+  | false
+  | null
+  | undefined
+  | Array<Child>;
+
+/** What is left of a child list once the empty entries and the nesting are gone. */
+type FlatChild = MarkupElement | StyleElement | string | number;
+
+/**
+ * Builds one element. Attribute values and text children are encoded on the way out.
+ */
+const el = (tag: Tag, attributes: Attributes = {}, ...children: Array<Child>): MarkupElement => ({
+  tag,
+  attributes,
+  children,
+});
+
+/**
+ * Builds the `<style>` element from a stylesheet rather than from text.
+ */
+const style = (...rules: Array<CssChild>): StyleElement => ({ tag: 'style', rules });
+
+const isStyle = (child: MarkupElement | StyleElement): child is StyleElement => 'rules' in child;
+
+/** Drops the children that carry nothing and flattens the arrays. */
+const flatten = (children: Array<Child>, into: Array<FlatChild> = []): Array<FlatChild> => {
+  for (const child of children) {
+    if (child === false || child === null || child === undefined || child === '') {
+      continue;
+    }
+    if (Array.isArray(child)) {
+      flatten(child, into);
+    } else {
+      into.push(child);
+    }
+  }
+  return into;
+};
+
+const openTag = (node: MarkupElement, selfClosing: boolean): string => {
+  let tag = `<${node.tag}`;
+  const { attributes } = node;
+
+  // `Object.keys` widens to `string`, so the cast restores what the type already says.
+  for (const name of Object.keys(attributes) as Array<Attribute>) {
+    const value = attributes[name];
+    if (value !== undefined) {
+      // A number can hold nothing that needs escaping, so it skips the scan.
+      tag += typeof value === 'number' ? ` ${name}="${value}"` : ` ${name}="${encodeHTML(value)}"`;
+    }
+  }
+
+  return `${tag}${selfClosing ? ' />' : '>'}`;
+};
+
+/** Serializes an element and its descendants onto one line, whitespace and all. */
+const writeInline = (node: FlatChild): string => {
+  if (typeof node === 'string') {
+    return encodeHTML(node);
+  }
+  if (typeof node === 'number') {
+    return String(node);
+  }
+  if (isStyle(node)) {
+    return '';
+  }
+
+  const children = flatten(node.children);
+  if (children.length === 0) {
+    return openTag(node, true);
+  }
+
+  let inner = '';
+  for (const child of children) {
+    inner += writeInline(child);
+  }
+  return `${openTag(node, false)}${inner}</${node.tag}>`;
+};
+
+/**
+ * A container is written optimistically and rewound if its content turns out empty,
+ * so an element that draws nothing costs one walk rather than two.
+ */
+const write = (node: FlatChild, depth: number, sink: Sink): void => {
+  const indent = indentAt(depth);
+
+  if (typeof node === 'string') {
+    sink.out += `${indent}${encodeHTML(node)}\n`;
+    return;
+  }
+  if (typeof node === 'number') {
+    sink.out += `${indent}${node}\n`;
+    return;
+  }
+
+  const mark = sink.out.length;
+
+  if (isStyle(node)) {
+    sink.out += `${indent}<style>\n`;
+    const bodyStart = sink.out.length;
+    writeCss(node.rules, depth + 1, sink);
+    sink.out =
+      sink.out.length === bodyStart ? sink.out.slice(0, mark) : `${sink.out}${indent}</style>\n`;
+    return;
+  }
+
+  const children = flatten(node.children);
+  if (children.length === 0) {
+    sink.out += `${indent}${openTag(node, true)}\n`;
+    return;
+  }
+
+  if (INLINE_ELEMENTS.has(node.tag)) {
+    let inner = '';
+    for (const child of children) {
+      inner += writeInline(child);
+    }
+    sink.out +=
+      inner === ''
+        ? `${indent}${openTag(node, true)}\n`
+        : `${indent}${openTag(node, false)}${inner}</${node.tag}>\n`;
+    return;
+  }
+
+  sink.out += `${indent}${openTag(node, false)}\n`;
+  const bodyStart = sink.out.length;
+  for (const child of children) {
+    write(child, depth + 1, sink);
+  }
+  sink.out =
+    sink.out.length === bodyStart
+      ? `${sink.out.slice(0, mark)}${indent}${openTag(node, true)}\n`
+      : `${sink.out}${indent}</${node.tag}>\n`;
+};
+
+/**
+ * Serializes a finished card: one element per line, two spaces per nesting level.
+ *
+ * @returns The rendered SVG.
+ */
+const renderMarkup = (root: MarkupElement): string => {
+  const sink: Sink = { out: '' };
+  write(root, 0, sink);
+  return sink.out;
+};
+
+export { el, renderMarkup, style };
+export type { Child, MarkupElement };

package/src/markup/html.ts

@@ -0,0 +1,34 @@
+/**
+ * What has to be encoded: the markup characters, everything above plain ASCII, and a backspace.
+ * One source for both regexes, so the check and the replacement cannot disagree.
+ */
+const ENCODED = String.raw`[<>&"'\u00A0-\u9999\u0008]`;
+
+/** Non-global, so `.test` stays stateless: a global regex would carry `lastIndex`. */
+const NEEDS_ENCODING = new RegExp(ENCODED);
+const TO_ENCODE = new RegExp(ENCODED, 'g');
+
+const BACKSPACE = '\u0008';
+
+/**
+ * Encodes a string for use as markup, one numeric character reference each.
+ *
+ * The serializer is now the only place text becomes markup, so nothing arrives pre-escaped:
+ * a literal `&#38;` is encoded like any other `&` rather than passed through as a reference.
+ *
+ * @see https://stackoverflow.com/a/48073476/10629172
+ *
+ * @returns The text, safe to place in an attribute or as character data.
+ */
+const encodeHTML = (str: string): string => {
+  // Most strings a card writes are plain ASCII, so they leave without a rewrite.
+  if (!NEEDS_ENCODING.test(str)) {
+    return str;
+  }
+
+  return str.replace(TO_ENCODE, (char) =>
+    char === BACKSPACE ? '' : `&#${char.codePointAt(0) ?? 0};`,
+  );
+};
+
+export { encodeHTML };

package/src/markup/index.ts

@@ -0,0 +1,9 @@
+/**
+ * The markup layer: a card is built as a tree of elements and rules, then serialized once.
+ * It depends on nothing else in the package, so it sits below `cards/`, not inside `common/`.
+ */
+
+export { atRule, cssComment, rule } from './css.ts';
+export type { CssChild, Declarations } from './css.ts';
+export { el, renderMarkup, style } from './element.ts';
+export type { Child, MarkupElement } from './element.ts';

package/src/markup/serialize.ts

@@ -0,0 +1,27 @@
+/**
+ * What the markup and stylesheet serializers share: where output goes, and how deep a line sits.
+ * Both write into one growing string rather than a list of chunks, so nothing needs joining.
+ */
+
+const INDENT = '  ';
+
+/** Collects serializer output. A plain holder so appends stay a property write. */
+interface Sink {
+  out: string;
+}
+
+/** Indentation by depth, grown as the tree is walked rather than rebuilt per line. */
+const indents = ['', INDENT];
+
+/**
+ * @returns Two spaces per level.
+ */
+const indentAt = (depth: number): string => {
+  for (let i = indents.length; i <= depth; i += 1) {
+    indents.push(`${indents[i - 1] ?? ''}${INDENT}`);
+  }
+  return indents[depth] ?? '';
+};
+
+export { INDENT, indentAt };
+export type { Sink };

package/src/themes/index.ts

@@ -10,12 +10,12 @@ interface Theme {
  * Collection of available themes.
  */
 export const themes = {
+  // No `border_color`: it is derived from the background, so a custom `bg_color` keeps its own.
   default: {
     title_color: '2f80ed',
     icon_color: '4c71f2',
     text_color: '434d58',
     bg_color: 'fffefe',
-    border_color: 'e4e2e2',
   },
   default_repocard: {
     title_color: '2f80ed',