@lostgradient/cinder 0.1.1 → 0.3.0

package/src/components/spectrogram/spectrogram.examples.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "spectrogram",
+  "import": "@lostgradient/cinder/spectrogram",
+  "examples": [
+    {
+      "id": "empty",
+      "title": "Empty state",
+      "description": "When no `frames` are available, supply an `empty` snippet to explain the absence instead of rendering a blank heatmap.",
+      "code": "<script lang=\"ts\">\n  import { Spectrogram } from '@lostgradient/cinder/spectrogram';\n</script>\n\n<Spectrogram label=\"Voice spectrogram\" frames={[]} height={220}>\n  {#snippet empty()}\n    No audio analyzed yet.\n  {/snippet}\n</Spectrogram>\n"
+    },
+    {
+      "id": "loading",
+      "title": "Loading state",
+      "description": "While frames are still being analyzed, set `loading` and supply a `loadingContent` snippet to render a placeholder over the heatmap.",
+      "code": "<script lang=\"ts\">\n  import { Spectrogram } from '@lostgradient/cinder/spectrogram';\n</script>\n\n<Spectrogram label=\"Voice spectrogram\" frames={[]} height={220} loading>\n  {#snippet loadingContent()}\n    Analyzing frequencies…\n  {/snippet}\n</Spectrogram>\n"
+    },
+    {
+      "id": "voice-spectrogram",
+      "title": "Voice spectrogram",
+      "description": "Time × frequency heatmap showing how frequency content changes over time.",
+      "code": "<script lang=\"ts\">\n  import { Spectrogram } from '@lostgradient/cinder/spectrogram';\n\n  const frequencyLabels = [\n    '50 Hz',\n    '100 Hz',\n    '200 Hz',\n    '400 Hz',\n    '800 Hz',\n    '1.6 kHz',\n    '3.2 kHz',\n    '6.4 kHz',\n  ];\n\n  // Simulate a vowel formant pattern changing over time\n  function makeFrame(\n    label: string,\n    formant1: number,\n    formant2: number,\n  ): { label: string; bins: number[] } {\n    return {\n      label,\n      bins: frequencyLabels.map((_, index) => {\n        const f1 = Math.exp(-Math.pow(index - formant1, 2) / 1.5) * 0.9;\n        const f2 = Math.exp(-Math.pow(index - formant2, 2) / 1.5) * 0.6;\n        // Deterministic micro-variation using index and formant positions\n        const microVariation = Math.sin(index * 17.3 + formant1 * 5.7) * 0.025;\n        return Math.min(1, f1 + f2 + Math.abs(microVariation));\n      }),\n    };\n  }\n\n  const frames = [\n    makeFrame('0 ms', 1, 4),\n    makeFrame('20 ms', 1.2, 4.2),\n    makeFrame('40 ms', 1.5, 4.5),\n    makeFrame('60 ms', 2, 5),\n    makeFrame('80 ms', 2.5, 5.5),\n    makeFrame('100 ms', 2.2, 5.2),\n    makeFrame('120 ms', 1.8, 4.8),\n    makeFrame('140 ms', 1.5, 4.5),\n    makeFrame('160 ms', 1.2, 4.2),\n    makeFrame('180 ms', 1, 4),\n  ];\n</script>\n\n<Spectrogram\n  label=\"Voice spectrogram — vowel formant transition\"\n  description=\"Time × frequency heatmap showing vowel formant frequency shifts over 180 ms.\"\n  {frames}\n  {frequencyLabels}\n  height={220}\n  dataTableVisibility=\"visible\"\n/>\n"
+    }
+  ]
+}

package/src/components/spectrogram/spectrogram.svelte

@@ -0,0 +1,284 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category data-display
+   * @status alpha
+   * @purpose Responsive SVG time × frequency heatmap for visualizing audio spectrogram data.
+   * @tag chart
+   * @tag spectrogram
+   * @tag signal
+   * @tag audio
+   * @useWhen Visualizing how frequency content of a signal changes over time (time × frequency heatmap).
+   * @useWhen Displaying pre-computed spectrogram frames from an FFT or short-time Fourier transform.
+   * @avoidWhen Only a single spectrum snapshot is needed — use spectrum-chart instead.
+   * @avoidWhen Real-time live audio spectrogram is needed — feed frames as props yourself.
+   * @avoidWhen A categorical × categorical heatmap without a time axis is needed — use matrix-chart instead.
+   * @related spectrum-chart, waveform, matrix-chart
+   */
+  export type {
+    SpectrogramFrame,
+    SpectrogramProps,
+    SpectrogramSchemaProps,
+  } from './spectrogram.types.ts';
+</script>
+
+<script lang="ts">
+  import { dataTableClass } from '../../_internal/chart/chart-utilities.ts';
+  import {
+    heatmapCellFill,
+    heatmapDomainOfRows,
+    toFiniteOrNull,
+  } from '../../_internal/chart/heatmap-utilities.ts';
+  import { classNames } from '../../utilities/class-names.ts';
+  import type { SpectrogramProps } from './spectrogram.types.ts';
+
+  let {
+    label,
+    description,
+    frames,
+    frequencyLabels,
+    height = 200,
+    loading = false,
+    dataTableVisibility = 'screen-reader-only',
+    dataTableCaption,
+    class: customClassName,
+    empty,
+    loadingContent,
+    id,
+    ...rest
+  }: SpectrogramProps = $props();
+
+  const generatedId = $props.id();
+  const rootId = $derived(id ?? generatedId);
+  const descriptionId = $derived(description ? `${rootId}-description` : undefined);
+
+  const marginTop = 8;
+  const marginRight = 16;
+  const marginBottom = 32;
+  const marginLeft = 60;
+
+  let measuredWidth = $state(400);
+  let rootElement = $state<HTMLElement>();
+
+  $effect(() => {
+    const element = rootElement;
+    if (!element) return;
+    // Guard for SSR / test environments without ResizeObserver.
+    if (typeof ResizeObserver === 'undefined') {
+      const rect = element.getBoundingClientRect();
+      if (rect.width > 0) measuredWidth = rect.width;
+      return;
+    }
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      // Ignore zero-width measurements (hidden / display:none) so the last good
+      // width is kept rather than collapsing the geometry, matching the fallback.
+      if (entry && entry.contentRect.width > 0) measuredWidth = entry.contentRect.width;
+    });
+    observer.observe(element);
+    return () => observer.disconnect();
+  });
+
+  const plotWidth = $derived(Math.max(1, measuredWidth - marginLeft - marginRight));
+  const plotHeight = $derived(Math.max(1, height - marginTop - marginBottom));
+
+  // Frequency-bin count is the MAX across frames so ragged input renders a full
+  // rectangular grid: shorter frames leave explicit missing cells rather than
+  // overflowing the plot or silently dropping rows.
+  const binCount = $derived(frames.reduce((max, frame) => Math.max(max, frame.bins.length), 0));
+
+  // The bin-index list [0, 1, …, binCount-1], computed once and reused for every
+  // frame's column rather than rebuilding an Array.from() per frame in the render
+  // loop.
+  const binIndices = $derived(Array.from({ length: binCount }, (_, index) => index));
+
+  // A frame with zero bins contributes no usable data; the chart is "empty" when
+  // there are no frames OR no frequency bins anywhere.
+  const isEmpty = $derived(frames.length === 0 || binCount === 0);
+
+  // Cell dimensions
+  const cellWidth = $derived(frames.length > 0 ? plotWidth / frames.length : 0);
+  const cellHeight = $derived(binCount > 0 ? plotHeight / binCount : 0);
+
+  // Read a frame's bin as a finite value or null (missing). Non-finite values
+  // (NaN/Infinity) and out-of-range indices (ragged frames) are missing.
+  function binValueAt(frameIndex: number, binIndex: number): number | null {
+    return toFiniteOrNull(frames[frameIndex]?.bins[binIndex]);
+  }
+
+  // Global color domain over the finite values only (shared with MatrixChart).
+  // Computed in a single nested pass over the frames so a large frames × bins
+  // grid never materializes a full flattened copy of every bin.
+  const domain = $derived(heatmapDomainOfRows(frames.map((frame) => frame.bins)));
+
+  function cellFill(value: number | null): string {
+    return heatmapCellFill(value, domain, 'sequential');
+  }
+
+  // Convert a bin index to a y-coordinate. Frequency increases UPWARD (the audio
+  // convention): bin 0 (lowest frequency) sits at the BOTTOM of the plot.
+  function binY(binIndex: number): number {
+    return plotHeight - (binIndex + 1) * cellHeight;
+  }
+
+  // Frequency axis labels, one per bin index. A PARTIAL `frequencyLabels` is
+  // honoured per-index — a provided label is used where present, and bins beyond
+  // its length fall back to the numeric index (rather than discarding all of the
+  // provided labels just because later/ragged frames added extra bins).
+  const yLabels = $derived.by(() =>
+    Array.from({ length: binCount }, (_, index) => frequencyLabels?.[index] ?? String(index)),
+  );
+
+  // Show a subset of y-axis labels
+  const maxYLabels = 8;
+  const yLabelStep = $derived(Math.max(1, Math.ceil(binCount / maxYLabels)));
+
+  // Show a subset of x-axis (time) labels
+  const maxXLabels = 10;
+  const xLabelStep = $derived(Math.max(1, Math.ceil(frames.length / maxXLabels)));
+
+  const hasDataTable = $derived(dataTableVisibility !== 'hidden');
+
+  // Table rows: each frame is a column; rows are frequency bins.
+  // For accessibility, sample every-Nth frame and bin so the full range is represented
+  // rather than silently truncating to first-N.
+  const maxTableFrames = 10;
+  const maxTableBins = 10;
+  const tableFrameStep = $derived(Math.max(1, Math.ceil(frames.length / maxTableFrames)));
+  const tableBinStep = $derived(Math.max(1, Math.ceil(binCount / maxTableBins)));
+  const tableFrames = $derived(
+    frames
+      .map((frame, frameIndex) => ({ frame, frameIndex }))
+      .filter((_, index) => index % tableFrameStep === 0)
+      .slice(0, maxTableFrames),
+  );
+  // Bins listed top-to-bottom to MATCH the visual: the SVG places bin 0 (lowest
+  // frequency) at the bottom, so the table's first row is the highest sampled
+  // bin and the last row is bin 0 — a screen-reader user reads the same vertical
+  // frequency order they would see.
+  const tableBinIndices = $derived(
+    Array.from({ length: binCount }, (_, index) => index)
+      .filter((index) => index % tableBinStep === 0)
+      .slice(0, maxTableBins)
+      .reverse(),
+  );
+  const isTruncated = $derived(frames.length > maxTableFrames || binCount > maxTableBins);
+  const tableCaption = $derived(
+    isTruncated
+      ? `${dataTableCaption ?? label} (showing ${tableFrames.length} of ${frames.length} frames, ${tableBinIndices.length} of ${binCount} bins)`
+      : (dataTableCaption ?? label),
+  );
+
+  function formatValue(value: number | null): string {
+    if (value === null) return '—';
+    return new Intl.NumberFormat(undefined, { maximumFractionDigits: 3 }).format(value);
+  }
+</script>
+
+<figure
+  {...rest}
+  bind:this={rootElement}
+  id={rootId}
+  class={classNames('cinder-spectrogram', customClassName)}
+  aria-label={label}
+  aria-describedby={descriptionId}
+>
+  {#if description}
+    <p id={descriptionId} class="cinder-spectrogram__description">{description}</p>
+  {/if}
+  <div
+    class="cinder-spectrogram__viewport"
+    style:height="{height}px"
+    data-cinder-loading={loading || undefined}
+  >
+    {#if loading}
+      <div class="cinder-spectrogram__state">
+        {#if loadingContent}{@render loadingContent()}{:else}Loading…{/if}
+      </div>
+    {:else if isEmpty}
+      <div class="cinder-spectrogram__state">
+        {#if empty}{@render empty()}{:else}No spectrogram data{/if}
+      </div>
+    {/if}
+    <svg
+      role="img"
+      viewBox={`0 0 ${measuredWidth} ${height}`}
+      aria-hidden={loading || isEmpty ? 'true' : undefined}
+      aria-labelledby={!loading && !isEmpty ? `${rootId}-svg-title` : undefined}
+    >
+      {#if !loading && !isEmpty}
+        <title id="{rootId}-svg-title">{label}</title>
+      {/if}
+      <!-- The plot only renders with data and when not loading — otherwise the
+           cells/labels would draw under the loading or empty overlay (frames may
+           be present while loading, so isEmpty alone is not enough). -->
+      {#if !loading && !isEmpty}
+        <g transform={`translate(${marginLeft}, ${marginTop})`}>
+          <!-- Frequency cells: a full frames × binCount rectangular grid. Ragged or
+               non-finite cells render as the "missing" fill. Low frequency (bin 0)
+               is at the bottom. -->
+          {#each frames as _frame, frameIndex (frameIndex)}
+            {#each binIndices as binIndex (binIndex)}
+              <rect
+                class="cinder-spectrogram__cell"
+                x={frameIndex * cellWidth}
+                y={binY(binIndex)}
+                width={cellWidth}
+                height={cellHeight}
+                fill={cellFill(binValueAt(frameIndex, binIndex))}
+                aria-hidden="true"
+              />
+            {/each}
+          {/each}
+          <!-- Y-axis frequency labels (bin 0 / lowest frequency at the bottom) -->
+          {#each yLabels as yLabel, index (index)}
+            {#if index % yLabelStep === 0}
+              <text
+                class="cinder-spectrogram__tick-label"
+                x={-6}
+                y={binY(index) + cellHeight / 2}
+                text-anchor="end"
+                dominant-baseline="middle">{yLabel}</text
+              >
+            {/if}
+          {/each}
+          <!-- X-axis time labels -->
+          {#each frames as frame, index (index)}
+            {#if index % xLabelStep === 0}
+              <text
+                class="cinder-spectrogram__tick-label"
+                x={index * cellWidth + cellWidth / 2}
+                y={plotHeight + 16}
+                text-anchor="middle"
+                dominant-baseline="auto">{frame.label}</text
+              >
+            {/if}
+          {/each}
+        </g>
+      {/if}
+    </svg>
+  </div>
+  {#if hasDataTable}
+    <table class={dataTableClass(dataTableVisibility)}>
+      <caption>{tableCaption}</caption>
+      <thead>
+        <tr>
+          <th scope="col">Frequency bin</th>
+          {#each tableFrames as entry (entry.frameIndex)}
+            <th scope="col">{entry.frame.label}</th>
+          {/each}
+        </tr>
+      </thead>
+      <tbody>
+        {#each tableBinIndices as binIndex (binIndex)}
+          <tr>
+            <th scope="row">{yLabels[binIndex] ?? binIndex}</th>
+            {#each tableFrames as entry (entry.frameIndex)}
+              <td>{formatValue(binValueAt(entry.frameIndex, binIndex))}</td>
+            {/each}
+          </tr>
+        {/each}
+      </tbody>
+    </table>
+  {/if}
+</figure>

package/src/components/spectrogram/spectrogram.types.ts

@@ -0,0 +1,74 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ChartDataTableVisibility } from '../chart.types.ts';
+
+/**
+ * A single time-frame of frequency-bin magnitudes.
+ * `label` identifies the time point (e.g. '0 ms', '10 ms').
+ * `bins` is an ordered array of frequency-bin magnitudes, one per column.
+ *
+ * @schemaObject
+ */
+export type SpectrogramFrame = {
+  /** Time-axis label for this frame, e.g. '0 ms' or 't=0'. */
+  label: string;
+  /**
+   * Magnitude values per frequency bin. A consistent length across frames is
+   * preferred, but ragged frames are supported: the grid uses the maximum bin
+   * count across all frames and renders any missing bins in shorter frames as
+   * "missing" cells. Non-finite values (NaN/Infinity) also render as missing.
+   */
+  bins: number[];
+};
+
+export type SpectrogramProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
+  /** Accessible label for the chart. Required for screen readers. */
+  label: string;
+  /** Optional description rendered below the label. */
+  description?: string;
+  /**
+   * Ordered sequence of time-indexed frames. Each frame contains a label and an
+   * array of per-frequency-bin magnitudes.
+   */
+  frames: SpectrogramFrame[];
+  /**
+   * Optional frequency-bin labels for the y-axis (e.g. ['100 Hz', '200 Hz', …]).
+   * When omitted, bins are labelled by index.
+   */
+  frequencyLabels?: string[];
+  /** Pixel height of the chart. Default `200`. */
+  height?: number;
+  /** Whether the chart is in a loading state. */
+  loading?: boolean;
+  /** Controls data table visibility. Default `screen-reader-only`. */
+  dataTableVisibility?: ChartDataTableVisibility;
+  /** Custom data table caption; falls back to `label`. */
+  dataTableCaption?: string;
+  /** Custom class applied to the root element. */
+  class?: string;
+  /** Snippet rendered when there are no frames. */
+  empty?: Snippet;
+  /** Snippet rendered while loading. */
+  loadingContent?: Snippet;
+};
+
+export type SpectrogramSchemaProps = {
+  /** Accessible label for the chart. Required for screen readers. */
+  label: string;
+  /** Optional description rendered below the label. */
+  description?: string;
+  /** Ordered sequence of time-indexed frames. Each frame contains a label and an array of per-frequency-bin magnitudes. */
+  frames: SpectrogramFrame[];
+  /** Optional frequency-bin labels for the y-axis (e.g. ['100 Hz', '200 Hz', …]). When omitted, bins are labelled by index. */
+  frequencyLabels?: string[];
+  /** Pixel height of the chart. Default `200`. */
+  height?: number;
+  /** Whether the chart is in a loading state. Default `false`. */
+  loading?: boolean;
+  /** Controls data table visibility. Default `screen-reader-only`. */
+  dataTableVisibility?: ChartDataTableVisibility;
+  /** Custom data table caption; falls back to `label`. */
+  dataTableCaption?: string;
+  /** Custom class applied to the root element. */
+  class?: string;
+};

package/src/components/spectrum-chart/README.md

@@ -0,0 +1,59 @@
+# SpectrumChart
+
+Responsive SVG frequency-bin bar chart for visualizing audio spectrum magnitude data.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { SpectrumChart } from '@lostgradient/cinder/spectrum-chart';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Displaying pre-computed frequency-domain magnitude data from an FFT or spectrum analyzer.
+- Showing a static frequency response or spectrum snapshot with labelled frequency bins.
+
+### Avoid When
+
+- Real-time live audio spectrum is needed — feed live AnalyserNode data as props yourself.
+- A full time × frequency heatmap is needed — use spectrogram instead.
+- General categorical bar comparison — use bar-chart instead.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop                  | Type                                                | Required | Default | Description                                                                                                         |
+| --------------------- | --------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
+| `bins`                | { label: `string`; value: `number` }[]              | yes      | —       | Frequency bins with label + magnitude value.                                                                        |
+| `class`               | `string`                                            | no       | —       | Custom class applied to the root element.                                                                           |
+| `dataTableCaption`    | `string`                                            | no       | —       | Custom data table caption; falls back to `label`.                                                                   |
+| `dataTableVisibility` | `"screen-reader-only"` \| `"visible"` \| `"hidden"` | no       | —       | Controls data table visibility. Default `screen-reader-only`.                                                       |
+| `description`         | `string`                                            | no       | —       | Optional description rendered below the label.                                                                      |
+| `height`              | `number`                                            | no       | —       | Pixel height of the chart. Default `160`.                                                                           |
+| `label`               | `string`                                            | yes      | —       | Accessible label for the chart. Required for screen readers.                                                        |
+| `loading`             | `boolean`                                           | no       | —       | Whether the chart is in a loading state. Default `false`.                                                           |
+| `empty`               | `(opaque)`                                          | no       | —       | Snippet rendered when there are no bins. Not expressible in JSON Schema; see the component types for the signature. |
+| `loadingContent`      | `(opaque)`                                          | no       | —       | Snippet rendered while loading. Not expressible in JSON Schema; see the component types for the signature.          |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

package/src/components/spectrum-chart/index.ts

@@ -0,0 +1,10 @@
+import './spectrum-chart.css';
+import SpectrumChart from './spectrum-chart.svelte';
+
+export default SpectrumChart;
+export type {
+  SpectrumBin,
+  SpectrumChartProps,
+  SpectrumChartSchemaProps,
+} from './spectrum-chart.types.ts';
+export { SpectrumChart };

package/src/components/spectrum-chart/spectrum-chart.css

@@ -0,0 +1,49 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@layer cinder.components {
+  .cinder-spectrum-chart {
+    display: grid;
+    gap: var(--cinder-space-3);
+    color: var(--cinder-text);
+  }
+
+  .cinder-spectrum-chart__description {
+    margin: 0;
+    color: var(--cinder-text-muted);
+    font-size: var(--cinder-text-sm);
+  }
+
+  .cinder-spectrum-chart__viewport {
+    position: relative;
+  }
+
+  .cinder-spectrum-chart svg {
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+  }
+
+  .cinder-spectrum-chart__bar {
+    fill: var(--cinder-chart-series-1);
+    rx: 2;
+  }
+
+  .cinder-spectrum-chart__grid-line {
+    stroke: var(--cinder-border-muted);
+    stroke-dasharray: 3 3;
+  }
+
+  .cinder-spectrum-chart__tick-label {
+    fill: var(--cinder-text-muted);
+    font-size: var(--cinder-text-xs);
+  }
+
+  .cinder-spectrum-chart__state {
+    position: absolute;
+    inset: 0;
+    display: grid;
+    place-items: center;
+    color: var(--cinder-text-muted);
+    background: color-mix(in oklch, var(--cinder-surface) 88%, transparent);
+    z-index: 1;
+  }
+}

package/src/components/spectrum-chart/spectrum-chart.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "spectrum-chart",
+  "import": "@lostgradient/cinder/spectrum-chart",
+  "examples": [
+    {
+      "id": "frequency-spectrum",
+      "title": "Frequency spectrum",
+      "description": "Pre-computed FFT magnitude spectrum showing frequency content of a signal.",
+      "code": "<script lang=\"ts\">\n  import { SpectrumChart } from '@lostgradient/cinder/spectrum-chart';\n\n  // Simulate a spectrum with a peak around 440 Hz (A4 note)\n  const bins = [\n    { label: '55 Hz', value: 0.02 },\n    { label: '110 Hz', value: 0.05 },\n    { label: '220 Hz', value: 0.12 },\n    { label: '330 Hz', value: 0.18 },\n    { label: '440 Hz', value: 0.95 },\n    { label: '550 Hz', value: 0.15 },\n    { label: '660 Hz', value: 0.08 },\n    { label: '880 Hz', value: 0.04 },\n    { label: '1.1 kHz', value: 0.03 },\n    { label: '1.3 kHz', value: 0.02 },\n    { label: '1.76 kHz', value: 0.01 },\n    { label: '2.2 kHz', value: 0.005 },\n  ];\n</script>\n\n<SpectrumChart\n  label=\"Frequency spectrum — A4 note (440 Hz)\"\n  description=\"Magnitude spectrum of a 440 Hz sine wave showing the fundamental and harmonics.\"\n  {bins}\n  height={180}\n  dataTableVisibility=\"visible\"\n/>\n"
+    }
+  ]
+}