@alkemdotdev/alkemist-components 1.0.0-beta.1

package/src/AlkModel.astro

@@ -0,0 +1,100 @@
+---
+import './model.css';
+import './figure.css';
+
+export interface AlkModelProps {
+  /** A glTF 2.0 .glb or .gltf URL. Compression decoders are not included. */
+  src: string;
+  title: string;
+  description?: string;
+  /** Static image shown before loading and when WebGL is unavailable. */
+  poster?: string;
+  class?: string;
+}
+
+type Props = AlkModelProps;
+const { src, title, description, poster, class: className } = Astro.props;
+---
+
+<alk-model
+  class:list={['alk-model', className]}
+  data-src={src}
+  data-state="idle"
+>
+  <figure class="alk-figure" aria-label={title}>
+    <figcaption class="alk-model-heading alk-figure-heading">
+      <div>
+        <p class="alk-model-label alk-figure-label">3D model · glTF 2.0</p>
+        <h3 class="alk-figure-title">{title}</h3>
+        {
+          description && (
+            <p class="alk-model-description alk-figure-description">
+              {description}
+            </p>
+          )
+        }
+      </div>
+    </figcaption>
+    <div class="alk-model-viewport" aria-busy="false">
+      {
+        poster && (
+          <img
+            class="alk-model-poster"
+            src={poster}
+            alt={`Static view of ${title}`}
+            loading="lazy"
+            width="960"
+            height="640"
+          />
+        )
+      }
+      <canvas
+        aria-label={`${title}. Drag to orbit; use arrow keys to rotate and plus or minus to zoom.`}
+        role="img"
+        tabindex="0"></canvas>
+      <div class="alk-model-axis" aria-hidden="true">
+        <span>X</span><span>Y</span><span>Z</span>
+      </div>
+      <p class="alk-model-hint">Drag to orbit · scroll to zoom</p>
+    </div>
+    <div
+      class="alk-model-toolbar alk-figure-controls"
+      aria-label={`${title} controls`}
+    >
+      <div class="alk-model-presets" role="group" aria-label="Camera view">
+        <button type="button" data-view="perspective" disabled
+          >Reset view</button
+        >
+        <button type="button" data-view="front" disabled>Front</button>
+        <button type="button" data-view="top" disabled>Top</button>
+      </div>
+      <div class="alk-model-switches">
+        <label
+          ><input type="checkbox" data-wireframe disabled /> Wireframe</label
+        >
+        <label><input type="checkbox" data-spin disabled /> Spin</label>
+      </div>
+    </div>
+    <div class="alk-model-footer alk-figure-footer">
+      <p
+        class="alk-model-status alk-figure-status"
+        role="status"
+        aria-live="polite"
+      >
+        Interactive view loads when visible.
+      </p>
+      <a href={src} download>Download model <span aria-hidden="true">↓</span></a
+      >
+    </div>
+    <noscript
+      ><p class="alk-figure-caption">
+        Enable JavaScript to explore this model. The original file is available
+        above.
+      </p></noscript
+    >
+  </figure>
+</alk-model>
+
+<script>
+  import './model';
+</script>

package/src/AlkShader.astro

@@ -0,0 +1,130 @@
+---
+import './shader.css';
+import './figure.css';
+import { ALK_INKS } from '@alkemdotdev/alkemist-theme/palette';
+
+export interface AlkShaderProps {
+  title?: string;
+  /** Spatial frequency, clamped to the visible control's range of 3–18. */
+  frequency?: number;
+  /** Rotation of the two sources in degrees, clamped to 0–180. */
+  angle?: number;
+  class?: string;
+}
+type Props = AlkShaderProps;
+const {
+  title = 'Interference field',
+  frequency = 9,
+  angle = 24,
+  class: className,
+} = Astro.props;
+const initialFrequency = Math.max(
+  3,
+  Math.min(18, Number.isFinite(frequency) ? frequency : 9),
+);
+const initialAngle = Math.max(
+  0,
+  Math.min(180, Number.isFinite(angle) ? angle : 24),
+);
+const fallbackInks = ALK_INKS;
+---
+
+<alk-shader class:list={['alk-shader', className]} data-state="idle">
+  <figure class="alk-figure" aria-label={title}>
+    <figcaption class="alk-shader-heading alk-figure-heading">
+      <div>
+        <p class="alk-figure-label">Shader · two wave sources</p>
+        <h3 class="alk-figure-title">{title}</h3>
+      </div>
+      <span class="alk-shader-tag alk-figure-format">GLSL</span>
+    </figcaption>
+    <div class="alk-shader-viewport">
+      <svg
+        class="alk-shader-poster"
+        viewBox="0 0 960 520"
+        role="img"
+        aria-label="Static illustration of two overlapping concentric wave sources; the interactive shader loads when visible."
+      >
+        {
+          [-1, 1].map((side) => (
+            <g
+              transform={`translate(${480 + side * 145} 260)`}
+              fill="none"
+              stroke-width="2"
+            >
+              {Array.from({ length: 14 }, (_, index) => {
+                const { id, hex } = fallbackInks[index % fallbackInks.length];
+                return (
+                  <circle
+                    r={28 + index * 22}
+                    style={`stroke:var(--alk-ink-${id}, ${hex})`}
+                  />
+                );
+              })}
+            </g>
+          ))
+        }
+      </svg>
+      <canvas
+        role="img"
+        aria-label={`${title}: interference contours from two point sources, rendered with the eight Alkemist inks.`}
+      ></canvas>
+      <p class="alk-shader-coordinate" aria-hidden="true">
+        ψ = sin(k r₁ − φ) + sin(k r₂ − φ)
+      </p>
+    </div>
+    <div
+      class="alk-shader-controls alk-figure-controls"
+      aria-label={`${title} controls`}
+    >
+      <label
+        ><span
+          >Frequency <output data-frequency-output
+            >{initialFrequency.toFixed(1)}</output
+          ></span
+        ><input
+          type="range"
+          min="3"
+          max="18"
+          step="0.1"
+          value={initialFrequency}
+          data-frequency
+          disabled
+        /></label
+      >
+      <label
+        ><span
+          >Source angle <output data-angle-output
+            >{initialAngle.toFixed(0)}°</output
+          ></span
+        ><input
+          type="range"
+          min="0"
+          max="180"
+          step="1"
+          value={initialAngle}
+          data-angle
+          disabled
+        /></label
+      >
+      <button type="button" data-play aria-pressed="false" disabled
+        >Play waves</button
+      >
+    </div>
+    <div class="alk-shader-footer alk-figure-footer">
+      <p class="alk-figure-status" role="status" aria-live="polite">
+        Shader loads when visible.
+      </p>
+    </div>
+    <noscript
+      ><p class="alk-shader-nojs alk-figure-caption">
+        Enable JavaScript to change the frequency and angle or animate the
+        field.
+      </p></noscript
+    >
+  </figure>
+</alk-shader>
+
+<script>
+  import './shader';
+</script>

package/src/HeaderIcon.astro

@@ -0,0 +1,54 @@
+---
+interface Props {
+  name: 'light' | 'dark' | 'system' | 'menu' | 'check' | 'chevron';
+}
+const { name } = Astro.props;
+---
+
+<svg
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="1.5"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+  aria-hidden="true"
+>
+  {
+    name === 'light' && (
+      <>
+        <>
+          <circle cx="12" cy="12" r="4" />
+          <path d="M12 2v2m0 16v2M2 12h2m16 0h2M5 5l1.4 1.4m11.2 11.2L19 19M5 19l1.4-1.4M17.6 6.4 19 5" />
+        </>
+      </>
+    )
+  }
+  {
+    name === 'dark' && (
+      <path d="M20.7 13A8.8 8.8 0 0 1 11 3.3 8.8 8.8 0 1 0 20.7 13Z" />
+    )
+  }
+  {
+    name === 'system' && (
+      <>
+        <>
+          <rect x="3" y="4" width="18" height="13" rx="2" />
+          <path d="M8 21h8m-4-4v4" />
+        </>
+      </>
+    )
+  }
+  {
+    name === 'menu' && (
+      <>
+        <>
+          <path class="alk-menu-line alk-menu-line-top" d="M4 8h16" />
+          <path class="alk-menu-line alk-menu-line-bottom" d="M4 16h16" />
+        </>
+      </>
+    )
+  }
+  {name === 'check' && <path d="m5 12 4 4L19 6" />}
+  {name === 'chevron' && <path d="m9 5 7 7-7 7" />}
+</svg>

package/src/chart.css

@@ -0,0 +1,84 @@
+.alk-chart {
+  display: block;
+  min-width: 0;
+  width: 100%;
+  margin: 1.5rem 0;
+}
+.alk-chart-canvas {
+  width: 100%;
+  min-width: 0;
+  position: relative;
+  padding: 0 0.5rem 0.75rem;
+}
+.alk-chart-canvas .vega-embed {
+  display: block;
+  padding: 0;
+  width: 100%;
+}
+.alk-chart-canvas svg {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}
+.alk-chart[data-state='error'] .alk-chart-canvas {
+  min-height: 0 !important;
+}
+.alk-chart[data-state='error'] .alk-chart-hint {
+  display: none;
+}
+.alk-chart-tools:not(:has(button:not([hidden]))) {
+  display: none;
+}
+.alk-chart-hint {
+  color: var(--alk-muted, #5e5e5e);
+  font: 0.7rem/1.5 var(--alk-mono, ui-monospace, monospace);
+}
+.alk-chart-table {
+  border-top: 1px solid var(--alk-rule, #ccc);
+  margin: 0 var(--alk-figure-gutter);
+  font-size: 0.76rem;
+}
+.alk-chart-table summary {
+  cursor: pointer;
+  padding: 0.7rem 0;
+}
+.alk-chart-table-scroll {
+  max-height: 23rem;
+  overflow: auto;
+  margin-bottom: 0.85rem;
+}
+.alk-chart-table-scroll table {
+  font: 0.75rem var(--alk-mono, ui-monospace, monospace);
+  width: 100%;
+}
+.alk-chart-table-scroll caption {
+  text-align: left;
+  padding-bottom: 0.8rem;
+  color: var(--alk-muted, #5e5e5e);
+}
+.alk-chart-table-scroll th {
+  position: sticky;
+  top: 0;
+  background: var(--alk-paper, #fff);
+}
+.alk-chart-table-scroll td,
+.alk-chart-table-scroll th {
+  white-space: nowrap;
+  padding: 0.55rem 0.7rem;
+}
+#vg-tooltip-element {
+  font-family: var(--alk-sans, system-ui, sans-serif);
+  background: var(--alk-paper, #fff);
+  color: var(--alk-ink, #111);
+  border: 1px solid var(--alk-rule, #ccc);
+  border-radius: 4px;
+  box-shadow: 0 3px 18px #0002;
+}
+#vg-tooltip-element td.key {
+  color: var(--alk-muted, #5e5e5e);
+}
+@media (max-width: 600px) {
+  .alk-chart-hint {
+    width: 100%;
+  }
+}

package/src/chart.ts

@@ -0,0 +1,232 @@
+import { ALK_INKS } from '@alkemdotdev/alkemist-theme/palette';
+import type embed from 'vega-embed';
+import type { Result } from 'vega-embed';
+import {
+  alkChartInks,
+  createAlkChartSpec,
+  prepareAlkChartRows,
+  type AlkChartProps,
+  type AlkChartRow,
+  type AlkChartTheme,
+} from './charts';
+
+class AlkChartElement extends HTMLElement {
+  private config!: AlkChartProps;
+  private rows?: AlkChartRow[];
+  private raw?: AlkChartRow[];
+  private embed?: typeof embed;
+  private result?: Result;
+  private visible?: IntersectionObserver;
+  private resize?: ResizeObserver;
+  private abort?: AbortController;
+  private generation = 0;
+  private width = 0;
+  private resizeTimer?: number;
+  private themeChange = () => {
+    if (this.rows) void this.render();
+  };
+  private resetView = () => {
+    void this.render();
+  };
+  private retryLoad = () => {
+    void this.load();
+  };
+
+  connectedCallback() {
+    this.config = JSON.parse(this.dataset.config ?? '{}');
+    this.abort = new AbortController();
+    this.querySelector('[data-chart-reset]')?.addEventListener(
+      'click',
+      this.resetView,
+    );
+    this.querySelector('[data-chart-retry]')?.addEventListener(
+      'click',
+      this.retryLoad,
+    );
+    window.addEventListener('alk:theme-change', this.themeChange);
+    this.resize = new ResizeObserver(() => {
+      const width = Math.floor(this.canvas.clientWidth);
+      if (width === this.width || width <= 0) return;
+      this.width = width;
+      window.clearTimeout(this.resizeTimer);
+      // Tick density and legend columns are compiled from the container width.
+      // A new specification keeps those readable after a desktop/mobile resize.
+      this.resizeTimer = window.setTimeout(() => {
+        void this.render();
+      }, 120);
+    });
+    this.resize.observe(this.canvas);
+    this.visible = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((entry) => entry.isIntersecting)) {
+          this.visible?.disconnect();
+          void this.load();
+        }
+      },
+      { rootMargin: '160px' },
+    );
+    this.visible.observe(this);
+  }
+
+  disconnectedCallback() {
+    this.generation++;
+    this.abort?.abort();
+    this.visible?.disconnect();
+    this.resize?.disconnect();
+    window.clearTimeout(this.resizeTimer);
+    this.result?.finalize();
+    this.result = undefined;
+    window.removeEventListener('alk:theme-change', this.themeChange);
+    this.querySelector('[data-chart-reset]')?.removeEventListener(
+      'click',
+      this.resetView,
+    );
+    this.querySelector('[data-chart-retry]')?.removeEventListener(
+      'click',
+      this.retryLoad,
+    );
+  }
+
+  private get canvas() {
+    return this.querySelector<HTMLElement>('.alk-chart-canvas')!;
+  }
+
+  private setStatus(message: string, state: 'loading' | 'ready' | 'error') {
+    this.dataset.state = state;
+    this.querySelector('.alk-chart-status')!.textContent = message;
+    this.canvas.setAttribute('aria-busy', String(state === 'loading'));
+    const reset = this.querySelector<HTMLButtonElement>('[data-chart-reset]');
+    if (reset) reset.disabled = state !== 'ready';
+    this.querySelector<HTMLButtonElement>('[data-chart-retry]')!.hidden =
+      state !== 'error';
+  }
+
+  private async load() {
+    const generation = ++this.generation;
+    this.setStatus('Loading the CSV and chart engine…', 'loading');
+    try {
+      const [embedModule, vega, response] = await Promise.all([
+        import('vega-embed'),
+        import('vega'),
+        fetch(this.config.src, { signal: this.abort?.signal }),
+      ]);
+      if (!response.ok)
+        throw new Error(`CSV request failed (${response.status}).`);
+      const csv = await response.text();
+      if (!this.isConnected || generation !== this.generation) return;
+      const raw = vega.read(csv, { type: 'csv' }) as AlkChartRow[];
+      this.rows = prepareAlkChartRows(raw, this.config);
+      this.raw = raw;
+      this.embed = embedModule.default;
+      this.renderTable();
+      await this.render();
+    } catch (error) {
+      if (!this.isConnected || generation !== this.generation) return;
+      this.fail(error);
+    }
+  }
+
+  private resolveTheme(): AlkChartTheme {
+    const probe = document.createElement('span');
+    probe.style.display = 'none';
+    const figure = this.querySelector<HTMLElement>('.alk-figure')!;
+    figure.append(probe);
+    const resolve = (property: string, fallback: string) => {
+      probe.style.color = `var(${property}, ${fallback})`;
+      return getComputedStyle(probe).color;
+    };
+    const theme: AlkChartTheme = {
+      text: getComputedStyle(figure).color,
+      rule: resolve('--alk-rule', '#ccc'),
+      inks: Object.fromEntries(
+        alkChartInks.map((ink) => [
+          ink,
+          resolve(
+            `--alk-ink-${ink}`,
+            ALK_INKS.find((color) => color.id === ink)!.hex,
+          ),
+        ]),
+      ) as AlkChartTheme['inks'],
+    };
+    probe.remove();
+    return theme;
+  }
+
+  private async render() {
+    if (!this.rows || !this.embed || !this.isConnected) return;
+    window.clearTimeout(this.resizeTimer);
+    const generation = ++this.generation;
+    this.setStatus('Rendering the chart…', 'loading');
+    try {
+      this.width = Math.max(1, Math.floor(this.canvas.clientWidth));
+      const mount = document.createElement('div');
+      const result = await this.embed(
+        mount,
+        createAlkChartSpec(
+          this.config,
+          this.rows,
+          this.resolveTheme(),
+          this.width,
+        ),
+        {
+          actions: false,
+          renderer: 'svg',
+          defaultStyle: false,
+          tooltip: { theme: 'custom' },
+        },
+      );
+      if (!this.isConnected || generation !== this.generation) {
+        result.finalize();
+        return;
+      }
+      this.result?.finalize();
+      this.result = result;
+      this.canvas.replaceChildren(mount);
+      this.setStatus(
+        `${this.rows.length.toLocaleString()} rows loaded from CSV.`,
+        'ready',
+      );
+    } catch (error) {
+      if (this.isConnected && generation === this.generation) this.fail(error);
+    }
+  }
+
+  private fail(error: unknown) {
+    this.result?.finalize();
+    this.result = undefined;
+    this.canvas.replaceChildren();
+    this.setStatus(
+      `Chart unavailable: ${error instanceof Error ? error.message : 'An unexpected error occurred.'} The source CSV is still available below.`,
+      'error',
+    );
+  }
+
+  private renderTable() {
+    if (!this.raw) return;
+    const fields = Object.keys(this.raw[0]);
+    const visibleRows = this.raw.slice(0, 100);
+    const table = document.createElement('table');
+    const caption = table.createCaption();
+    caption.textContent = `${this.config.title}. ${this.raw.length > 100 ? `Showing the first 100 of ${this.raw.length} rows; download the CSV for all rows.` : `All ${this.raw.length} source rows.`} Empty cells are missing values.`;
+    const heading = table.createTHead().insertRow();
+    for (const field of fields) {
+      const cell = document.createElement('th');
+      cell.scope = 'col';
+      cell.textContent = field;
+      heading.append(cell);
+    }
+    const body = table.createTBody();
+    for (const row of visibleRows) {
+      const tr = body.insertRow();
+      for (const field of fields)
+        tr.insertCell().textContent =
+          row[field] === null ? '' : String(row[field]);
+    }
+    this.querySelector('.alk-chart-table-scroll')!.replaceChildren(table);
+    this.querySelector('[data-chart-count]')!.textContent =
+      `(${this.raw.length.toLocaleString()} rows)`;
+  }
+}
+
+if (!customElements.get('alk-chart'))
+  customElements.define('alk-chart', AlkChartElement);