@alkemdotdev/alkemist-components 1.0.0-beta.1

package/src/charts.ts

@@ -0,0 +1,401 @@
+import type { TopLevelSpec } from 'vega-lite';
+
+export type AlkChartType =
+  'line' | 'bar' | 'scatter' | 'pie' | 'donut' | 'heatmap';
+export type AlkChartFieldType =
+  'quantitative' | 'temporal' | 'nominal' | 'ordinal';
+export type AlkChartInk =
+  | 'cobalt'
+  | 'cyan'
+  | 'teal'
+  | 'fern'
+  | 'ochre'
+  | 'vermilion'
+  | 'rose'
+  | 'violet';
+
+export interface AlkChartProps {
+  src: string;
+  type: AlkChartType;
+  x: string;
+  y: string;
+  title: string;
+  description: string;
+  xLabel?: string;
+  yLabel?: string;
+  xType?: AlkChartFieldType;
+  color?: string;
+  colorLabel?: string;
+  value?: string;
+  valueLabel?: string;
+  ink?: AlkChartInk;
+  height?: number;
+  grid?: boolean;
+  zoom?: boolean;
+  horizontal?: boolean;
+  stacked?: boolean;
+  caption?: string;
+  sample?: boolean;
+}
+
+export interface AlkChartTheme {
+  text: string;
+  rule: string;
+  inks: Record<AlkChartInk, string>;
+}
+
+export type AlkChartRow = Record<string, string | number | null>;
+
+export const alkChartInks: AlkChartInk[] = [
+  'cobalt',
+  'cyan',
+  'teal',
+  'fern',
+  'ochre',
+  'vermilion',
+  'rose',
+  'violet',
+];
+
+function literalField(field: string): string {
+  return field
+    .replaceAll('\\', '\\\\')
+    .replaceAll('.', '\\.')
+    .replaceAll('[', '\\[')
+    .replaceAll(']', '\\]');
+}
+
+export function alkChartXType(config: AlkChartProps): AlkChartFieldType {
+  return (
+    config.xType ??
+    (['bar', 'pie', 'donut'].includes(config.type)
+      ? 'nominal'
+      : config.type === 'heatmap'
+        ? 'ordinal'
+        : 'quantitative')
+  );
+}
+
+export function alkChartCanZoom(config: AlkChartProps): boolean {
+  return (
+    config.zoom !== false &&
+    ['line', 'scatter'].includes(config.type) &&
+    ['quantitative', 'temporal'].includes(alkChartXType(config))
+  );
+}
+
+/** Parse only explicitly numeric columns; identifiers and category labels stay intact. */
+export function prepareAlkChartRows(
+  raw: AlkChartRow[],
+  config: AlkChartProps,
+): AlkChartRow[] {
+  if (!raw.length) throw new Error('The CSV contains no data rows.');
+  const required = [
+    config.x,
+    config.y,
+    config.color,
+    config.type === 'heatmap' ? config.value : undefined,
+  ].filter((field): field is string => Boolean(field));
+  if (config.type === 'heatmap' && !config.value)
+    throw new Error('A heatmap requires a value column.');
+  for (const field of required) {
+    if (!Object.hasOwn(raw[0], field))
+      throw new Error(`The CSV is missing the “${field}” column.`);
+  }
+  const numeric = new Set<string>();
+  if (alkChartXType(config) === 'quantitative') numeric.add(config.x);
+  if (config.type !== 'heatmap') numeric.add(config.y);
+  if (config.type === 'heatmap' && config.value) numeric.add(config.value);
+  if (config.type === 'heatmap') {
+    for (const field of [config.x, config.y]) {
+      if (
+        raw.every(
+          (row) =>
+            row[field] !== null &&
+            String(row[field]).trim() !== '' &&
+            Number.isFinite(Number(row[field])),
+        )
+      )
+        numeric.add(field);
+    }
+  }
+  const rows = raw.map((source, index) => {
+    const row = { ...source };
+    for (const field of numeric) {
+      const value = source[field];
+      if (value === null || String(value).trim() === '') {
+        row[field] = null;
+      } else {
+        const number = Number(value);
+        if (!Number.isFinite(number))
+          throw new Error(
+            `Row ${index + 2}: “${field}” must contain a finite number.`,
+          );
+        if (
+          ['pie', 'donut'].includes(config.type) &&
+          field === config.y &&
+          number < 0
+        )
+          throw new Error(
+            `Row ${index + 2}: pie and donut values cannot be negative.`,
+          );
+        row[field] = number;
+      }
+    }
+    if (alkChartXType(config) === 'temporal') {
+      const value = row[config.x];
+      if (value === null || String(value).trim() === '') {
+        row[config.x] = null;
+      } else if (!Number.isFinite(Date.parse(String(value)))) {
+        throw new Error(
+          `Row ${index + 2}: “${config.x}” must contain a valid date.`,
+        );
+      }
+    }
+    return row;
+  });
+  for (const field of numeric) {
+    if (rows.every((row) => row[field] === null))
+      throw new Error(`The “${field}” column contains no numeric values.`);
+  }
+  if (
+    alkChartXType(config) === 'temporal' &&
+    rows.every((row) => row[config.x] === null)
+  )
+    throw new Error(`The “${config.x}” column contains no dates.`);
+  if (
+    ['pie', 'donut'].includes(config.type) &&
+    !rows.some((row) => Number(row[config.y]) > 0)
+  )
+    throw new Error(
+      'Pie and donut charts require at least one positive value.',
+    );
+  return rows;
+}
+
+/** Presets remain small; the Vega-Lite engine owns scales, marks, and interactions. */
+export function createAlkChartSpec(
+  config: AlkChartProps,
+  rows: AlkChartRow[],
+  theme: AlkChartTheme,
+  width: number,
+): TopLevelSpec {
+  const palette = alkChartInks.map((ink) => theme.inks[ink]);
+  const categorical =
+    config.color ??
+    (['bar', 'pie', 'donut'].includes(config.type) ? config.x : undefined);
+  const color = categorical
+    ? {
+        field: literalField(categorical),
+        type: 'nominal' as const,
+        title: config.colorLabel ?? categorical,
+        scale: {
+          domain: [...new Set(rows.map((row) => row[categorical]))],
+          range: palette,
+        },
+        legend:
+          config.type === 'bar' && !config.color
+            ? null
+            : {
+                orient: 'bottom' as const,
+                columns: width < 420 ? 2 : 4,
+                labelLimit: Math.max(65, width / (width < 420 ? 2 : 4) - 42),
+              },
+      }
+    : { value: theme.inks[config.ink ?? 'cobalt'] };
+  const base = {
+    $schema: 'https://vega.github.io/schema/vega-lite/v6.json',
+    description: config.description,
+    width,
+    height: config.height ?? 300,
+    padding: 6,
+    autosize: { type: 'fit' as const, contains: 'padding' as const },
+    background: 'transparent',
+    data: { values: rows },
+    config: {
+      font: 'Ubuntu',
+      view: { stroke: null },
+      axis: {
+        grid: config.grid !== false,
+        gridColor: theme.rule,
+        domainColor: theme.rule,
+        tickColor: theme.rule,
+        labelColor: theme.text,
+        titleColor: theme.text,
+        labelFont: 'Ubuntu Mono',
+        titleFont: 'Ubuntu',
+        labelFontSize: 12,
+        titleFontSize: 12,
+        titleFontWeight: 400 as const,
+        titlePadding: 14,
+        labelPadding: 7,
+        labelLimit: 120,
+        tickCount: Math.max(3, Math.round(width / 100)),
+      },
+      legend: {
+        labelColor: theme.text,
+        titleColor: theme.text,
+        labelFont: 'Ubuntu',
+        titleFont: 'Ubuntu',
+        titleFontWeight: 400 as const,
+        labelFontSize: 12,
+        symbolSize: 80,
+        padding: 10,
+        rowPadding: 7,
+      },
+    },
+  };
+  const x = {
+    field: literalField(config.x),
+    type: alkChartXType(config),
+    title: config.xLabel ?? config.x,
+    axis:
+      config.type === 'bar' &&
+      !config.horizontal &&
+      width < 420 &&
+      ['nominal', 'ordinal'].includes(alkChartXType(config))
+        ? { labelAngle: -55, labelLimit: 70, labelOverlap: 'greedy' as const }
+        : { labelAngle: 0 },
+    ...(alkChartXType(config) === 'quantitative'
+      ? { scale: { zero: false } }
+      : {}),
+  };
+  const y = {
+    field: literalField(config.y),
+    type: 'quantitative' as const,
+    title: config.yLabel ?? config.y,
+  };
+  const tooltip = [
+    {
+      field: literalField(config.x),
+      type: alkChartXType(config),
+      title: config.xLabel ?? config.x,
+    },
+    {
+      field: literalField(config.y),
+      type:
+        config.type === 'heatmap'
+          ? ('ordinal' as const)
+          : ('quantitative' as const),
+      title: config.yLabel ?? config.y,
+    },
+    ...(config.color
+      ? [
+          {
+            field: literalField(config.color),
+            type: 'nominal' as const,
+            title: config.colorLabel ?? config.color,
+          },
+        ]
+      : []),
+  ];
+  if (config.type === 'pie' || config.type === 'donut') {
+    return {
+      ...base,
+      mark: {
+        type: 'arc',
+        innerRadius:
+          config.type === 'donut'
+            ? Math.min(width, config.height ?? 300) * 0.22
+            : 0,
+        padAngle: 0.015,
+        cornerRadius: 2,
+      },
+      encoding: { theta: { ...y, stack: true }, color, tooltip },
+    };
+  }
+  if (config.type === 'heatmap') {
+    return {
+      ...base,
+      mark: { type: 'rect', tooltip: true },
+      encoding: {
+        x: {
+          ...x,
+          scale: { paddingInner: 0.04 },
+          axis: { labelAngle: 0, labelOverlap: true },
+        },
+        y: {
+          field: literalField(config.y),
+          type: 'ordinal',
+          title: config.yLabel ?? config.y,
+          scale: { paddingInner: 0.04 },
+          sort: 'descending',
+          axis: { labelOverlap: true },
+        },
+        color: {
+          field: literalField(config.value!),
+          type: 'quantitative',
+          title: config.valueLabel ?? config.value,
+          scale: {
+            range: ['#253f67', theme.inks.cobalt, '#b6d6f6'],
+            interpolate: 'lab',
+          },
+          legend: {
+            orient: 'bottom',
+            gradientLength: Math.max(100, Math.min(240, width - 55)),
+          },
+        },
+        tooltip: [
+          ...tooltip,
+          {
+            field: literalField(config.value!),
+            type: 'quantitative',
+            title: config.valueLabel ?? config.value,
+          },
+        ],
+      },
+    };
+  }
+  if (config.type === 'bar') {
+    const magnitude = {
+      ...y,
+      stack: config.stacked ? ('zero' as const) : null,
+    };
+    return {
+      ...base,
+      mark: { type: 'bar', cornerRadiusEnd: 2 },
+      encoding: {
+        x: config.horizontal ? magnitude : x,
+        y: config.horizontal ? { ...x, axis: { labelAngle: 0 } } : magnitude,
+        ...(!config.stacked && config.color && config.color !== config.x
+          ? config.horizontal
+            ? { yOffset: { field: literalField(config.color) } }
+            : { xOffset: { field: literalField(config.color) } }
+          : {}),
+        color,
+        tooltip,
+      },
+    };
+  }
+  return {
+    ...base,
+    ...(alkChartCanZoom(config)
+      ? {
+          params: [
+            {
+              name: 'alk_window',
+              select: {
+                type: 'interval' as const,
+                encodings:
+                  config.type === 'scatter'
+                    ? ['x' as const, 'y' as const]
+                    : ['x' as const],
+                zoom: 'wheel![event.shiftKey]',
+              },
+              bind: 'scales' as const,
+            },
+          ],
+        }
+      : {}),
+    mark:
+      config.type === 'line'
+        ? {
+            type: 'line',
+            strokeWidth: 2.5,
+            clip: true,
+            point: { filled: true, size: 8 },
+          }
+        : { type: 'point', filled: true, size: 36, opacity: 0.85, clip: true },
+    encoding: { x, y: { ...y, scale: { zero: false } }, color, tooltip },
+  };
+}

package/src/code-copy.ts

@@ -0,0 +1,39 @@
+function enhanceCode() {
+  document
+    .querySelectorAll<HTMLButtonElement>('[data-alk-copy]')
+    .forEach((button) => {
+      button.hidden = false;
+      if (button.dataset.alkReady) return;
+      button.dataset.alkReady = 'true';
+      button.addEventListener('click', async () => {
+        const figure = button.closest('.alk-code');
+        const code = figure?.querySelector('pre code');
+        const status = figure?.querySelector<HTMLElement>(
+          '[data-alk-copy-status]',
+        );
+        if (!code || !status) return;
+        try {
+          await navigator.clipboard.writeText(code.textContent ?? '');
+          status.textContent = 'Code copied to clipboard.';
+          button.textContent = 'Copied';
+        } catch {
+          // Selection remains useful when a browser or its permissions block the clipboard.
+          const selection = window.getSelection();
+          const range = document.createRange();
+          range.selectNodeContents(code);
+          selection?.removeAllRanges();
+          selection?.addRange(range);
+          (figure?.querySelector('pre') as HTMLElement | null)?.focus();
+          status.textContent =
+            'Clipboard unavailable. Code selected; use your browser’s Copy command.';
+          button.textContent = 'Selected';
+        }
+        window.setTimeout(() => {
+          button.textContent = 'Copy';
+        }, 2400);
+      });
+    });
+}
+
+enhanceCode();
+document.addEventListener('astro:page-load', enhanceCode);

package/src/code-theme.ts

@@ -0,0 +1,199 @@
+import type { ShikiTransformer, ThemeRegistration } from 'shiki';
+import { ALK_INKS } from '@alkemdotdev/alkemist-theme/palette';
+
+const inks = Object.fromEntries(ALK_INKS.map(({ id, hex }) => [id, hex]));
+
+/** One fixed ink set on a black code surface, independent of the page theme. */
+export const AlkCodeTheme: ThemeRegistration = {
+  name: 'alkemist-board',
+  type: 'dark',
+  colors: { 'editor.background': '#111111', 'editor.foreground': '#eeeeee' },
+  tokenColors: [
+    {
+      scope: ['comment', 'punctuation.definition.comment'],
+      settings: { foreground: '#999999', fontStyle: 'italic' },
+    },
+    {
+      scope: [
+        'keyword',
+        'storage',
+        'punctuation.definition.template-expression',
+      ],
+      settings: { foreground: inks.violet },
+    },
+    {
+      scope: ['string', 'markup.inserted'],
+      settings: { foreground: inks.fern },
+    },
+    {
+      scope: ['constant.numeric', 'constant.language', 'support.constant'],
+      settings: { foreground: inks.ochre },
+    },
+    {
+      scope: ['entity.name.function', 'support.function'],
+      settings: { foreground: inks.cyan },
+    },
+    {
+      scope: [
+        'entity.name.type',
+        'support.type',
+        'support.class',
+        'entity.name.class',
+      ],
+      settings: { foreground: inks.cobalt },
+    },
+    {
+      scope: ['variable.parameter', 'entity.other.attribute-name'],
+      settings: { foreground: inks.rose },
+    },
+    {
+      scope: ['entity.name.tag', 'markup.deleted'],
+      settings: { foreground: inks.vermilion },
+    },
+    {
+      scope: ['markup.heading', 'markup.bold'],
+      settings: { foreground: '#eeeeee', fontStyle: 'bold' },
+    },
+    { scope: ['markup.italic'], settings: { fontStyle: 'italic' } },
+    {
+      scope: ['invalid'],
+      settings: { foreground: '#eeeeee', fontStyle: 'underline' },
+    },
+  ],
+};
+
+export interface AlkCodeOptions {
+  title?: string;
+  highlightLines?: number[];
+  lineNumbers?: boolean;
+}
+
+function metadata(raw: string, options: AlkCodeOptions) {
+  let metaTitle: string | undefined;
+  // Quoted captions are content; their braces and flag words must stay inert.
+  const flags = raw.replace(
+    /(?:^|\s)title="([^"]*)"/g,
+    (_match, value: string) => {
+      metaTitle ??= value;
+      return ' ';
+    },
+  );
+  const title = options.title ?? metaTitle;
+  const highlighted = flags.match(/(?:^|\s)\{([^}]+)\}/)?.[1];
+  const ranges =
+    highlighted?.split(',').map((range) => {
+      const match = range.trim().match(/^(\d+)(?:-(\d+))?$/);
+      if (!match)
+        throw new Error(`Alkemist: invalid code highlight range "${range}".`);
+      const start = Number(match[1]);
+      const end = Number(match[2] ?? match[1]);
+      if (start < 1 || end < start || !Number.isSafeInteger(end)) {
+        throw new Error(
+          `Alkemist: code highlight lines must be positive, increasing integers: "${range}".`,
+        );
+      }
+      return [start, end] as const;
+    }) ?? [];
+  if (
+    options.highlightLines?.some(
+      (line) => !Number.isSafeInteger(line) || line < 1,
+    )
+  ) {
+    throw new Error(
+      'Alkemist: highlightLines must contain positive integer line numbers.',
+    );
+  }
+  return {
+    title,
+    lineNumbers:
+      options.lineNumbers ?? !/(?:^|\s)no-line-numbers(?:\s|$)/.test(flags),
+    isHighlighted: (line: number) =>
+      options.highlightLines
+        ? options.highlightLines.includes(line)
+        : ranges.some(([start, end]) => line >= start && line <= end),
+  };
+}
+
+/** Shared by Markdown fences and AlkCode; all source and metadata become HAST text. */
+export function createAlkCodeTransformer(
+  options: AlkCodeOptions = {},
+): ShikiTransformer {
+  return {
+    name: 'alkemist-code',
+    pre(node) {
+      const config = metadata(this.options.meta?.__raw ?? '', options);
+      node.properties.tabindex = 0;
+      node.properties.ariaLabel = `${config.title ?? this.options.lang} source code`;
+      this.addClassToHast(node, 'alk-code-pre');
+      if (config.lineNumbers) this.addClassToHast(node, 'alk-code-numbered');
+    },
+    line(node, line) {
+      const config = metadata(this.options.meta?.__raw ?? '', options);
+      node.properties.dataLine = String(line);
+      if (config.isHighlighted(line))
+        this.addClassToHast(node, 'alk-code-highlight');
+    },
+    root(root) {
+      const config = metadata(this.options.meta?.__raw ?? '', options);
+      const children = root.children.map((child) => {
+        if (child.type === 'doctype') {
+          throw new Error(
+            'Alkemist: code highlighting must produce an HTML fragment.',
+          );
+        }
+        return child;
+      });
+      root.children = [
+        {
+          type: 'element',
+          tagName: 'figure',
+          properties: { className: ['alk-code'] },
+          children: [
+            {
+              type: 'element',
+              tagName: 'figcaption',
+              properties: { className: ['alk-code-caption'] },
+              children: [
+                {
+                  type: 'element',
+                  tagName: 'span',
+                  properties: { className: ['alk-code-title'] },
+                  children: [{ type: 'text', value: config.title ?? 'Source' }],
+                },
+                {
+                  type: 'element',
+                  tagName: 'span',
+                  properties: { className: ['alk-code-language'] },
+                  children: [{ type: 'text', value: this.options.lang }],
+                },
+                {
+                  type: 'element',
+                  tagName: 'button',
+                  properties: {
+                    type: 'button',
+                    className: ['alk-code-copy'],
+                    dataAlkCopy: '',
+                    hidden: true,
+                    ariaLabel: `Copy ${config.title ?? this.options.lang} source code`,
+                  },
+                  children: [{ type: 'text', value: 'Copy' }],
+                },
+                {
+                  type: 'element',
+                  tagName: 'span',
+                  properties: {
+                    className: ['alk-sr-only'],
+                    role: 'status',
+                    dataAlkCopyStatus: '',
+                  },
+                  children: [],
+                },
+              ],
+            },
+            ...children,
+          ],
+        },
+      ];
+    },
+  };
+}