@lostgradient/cinder 0.1.1 → 0.2.0

package/src/components/waveform/waveform.svelte

@@ -0,0 +1,286 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category data-display
+   * @status alpha
+   * @purpose Responsive SVG rendering of time-domain audio amplitude data as a waveform path or bar display.
+   * @tag chart
+   * @tag waveform
+   * @tag signal
+   * @tag audio
+   * @useWhen Visualizing pre-recorded or pre-processed audio amplitude samples in a static display.
+   * @useWhen Showing an audio waveform thumbnail or preview with mocked or pre-computed sample data.
+   * @avoidWhen Real-time live audio capture is needed — wire AudioContext / AnalyserNode yourself and feed samples as props.
+   * @avoidWhen Frequency-domain data — use spectrum-chart or spectrogram instead.
+   * @related spectrum-chart, spectrogram, bar-chart, line-chart
+   */
+  export type { WaveformProps, WaveformSchemaProps } from './waveform.types.ts';
+</script>
+
+<script lang="ts">
+  import { dataTableClass } from '../../_internal/chart/chart-utilities.ts';
+  import { classNames } from '../../utilities/class-names.ts';
+  import type { WaveformProps } from './waveform.types.ts';
+
+  let {
+    label,
+    description,
+    data,
+    renderMode = 'path',
+    height = 80,
+    loading = false,
+    dataTableVisibility = 'screen-reader-only',
+    dataTableCaption,
+    class: customClassName,
+    empty,
+    loadingContent,
+    id,
+    ...rest
+  }: WaveformProps = $props();
+
+  const generatedId = $props.id();
+  const rootId = $derived(id ?? generatedId);
+  const descriptionId = $derived(description ? `${rootId}-description` : undefined);
+
+  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 isEmpty = $derived(data.length === 0);
+  const midY = $derived(height / 2);
+
+  // Cap the number of rendered geometry points so a multi-million-sample buffer
+  // doesn't produce a megabyte-long path string or one <rect> per sample. We
+  // downsample with a min/max envelope per bucket so transients survive. The
+  // accessible table reports the ORIGINAL length and notes the sampling.
+  const MAX_RENDER_POINTS = 2000;
+
+  // Clamp a single sample to [-1, 1]; non-finite samples (NaN/Infinity) collapse
+  // to the baseline (0) rather than producing invalid SVG coordinates. Applied
+  // lazily per-sample so a multi-million-sample buffer is never copied wholesale
+  // — only the ~MAX_RENDER_POINTS values that actually render are materialized.
+  function clampSample(sample: number | undefined): number {
+    return sample !== undefined && Number.isFinite(sample) ? Math.max(-1, Math.min(1, sample)) : 0;
+  }
+
+  // Envelope-downsampled samples for rendering: each bucket contributes its min
+  // and max so peaks aren't lost. The two extremes are emitted in their ORIGINAL
+  // temporal order (min-then-max only if the min occurred first) so the rendered
+  // path doesn't invert the local waveform shape. Clamping is folded into this
+  // pass so the full input buffer is never duplicated. When the data already
+  // fits, we still produce a fresh clamped array of just `length` points.
+  const renderSamples = $derived.by((): number[] => {
+    const length = data.length;
+    if (length <= MAX_RENDER_POINTS) return data.map(clampSample);
+    const bucketCount = Math.floor(MAX_RENDER_POINTS / 2);
+    const bucketSize = length / bucketCount;
+    const out: number[] = [];
+    for (let bucket = 0; bucket < bucketCount; bucket += 1) {
+      const start = Math.floor(bucket * bucketSize);
+      // The final bucket extends to the end so the very last sample is included.
+      const end =
+        bucket === bucketCount - 1
+          ? length
+          : Math.min(length, Math.floor((bucket + 1) * bucketSize));
+      let min = clampSample(data[start]);
+      let max = min;
+      let minIndex = start;
+      let maxIndex = start;
+      for (let index = start; index < end; index += 1) {
+        const sample = clampSample(data[index]);
+        if (sample < min) {
+          min = sample;
+          minIndex = index;
+        }
+        if (sample > max) {
+          max = sample;
+          maxIndex = index;
+        }
+      }
+      if (minIndex <= maxIndex) out.push(min, max);
+      else out.push(max, min);
+    }
+    return out;
+  });
+
+  // Build a centered waveform path
+  const waveformPath = $derived.by(() => {
+    const samples = renderSamples;
+    if (samples.length === 0) return '';
+    // A single sample has no horizontal extent — draw a short centered tick so
+    // it is visible rather than dividing by (length - 1) === 0 → NaN.
+    if (samples.length === 1) {
+      const x = measuredWidth / 2;
+      const y = midY - samples[0]! * midY;
+      return `M${(x - 1).toFixed(2)},${y.toFixed(2)}L${(x + 1).toFixed(2)},${y.toFixed(2)}`;
+    }
+    const points = samples.map((sample, index) => {
+      const x = (index / (samples.length - 1)) * measuredWidth;
+      const y = midY - sample * midY;
+      return { x, y };
+    });
+    const firstPoint = points[0]!;
+    const restPoints = points.slice(1);
+    return (
+      `M${firstPoint.x.toFixed(2)},${firstPoint.y.toFixed(2)}` +
+      restPoints.map((point) => `L${point.x.toFixed(2)},${point.y.toFixed(2)}`).join('')
+    );
+  });
+
+  // Build bar segments for bars render mode
+  type WaveformBar = { x: number; y: number; height: number; width: number };
+  const waveformBars = $derived.by((): WaveformBar[] => {
+    const samples = renderSamples;
+    if (samples.length === 0) return [];
+    // x-STEP is the fractional slot width so bars always span exactly the
+    // viewport, even when there are more samples than pixels. The visible WIDTH
+    // is clamped to a 1px minimum independently (bars may visually overlap when
+    // the step is sub-pixel, which is the correct dense-waveform appearance).
+    const step = measuredWidth / samples.length;
+    const visualWidth = Math.max(1, step - 1);
+    return samples.map((sample, index) => {
+      const amplitude = Math.abs(sample);
+      // Zero amplitude renders zero height (just the baseline) — do NOT force a
+      // minimum 1px bar, which would make silence look like low-level signal.
+      const barHeight = amplitude * midY;
+      return {
+        x: index * step,
+        y: midY - barHeight,
+        height: barHeight * 2,
+        width: visualWidth,
+      };
+    });
+  });
+
+  const hasDataTable = $derived(dataTableVisibility !== 'hidden');
+
+  // Stride the clamped/sanitized SOURCE samples for the accessible table, capped
+  // at 20 rows so the table stays readable. The caption reports the true length +
+  // sampling. Clamping is applied lazily at the stride points so the full buffer
+  // is never copied here either.
+  //
+  // Deliberate: the table strides the original `data` (the true signal), NOT the
+  // min/max envelope that `renderSamples` draws for buffers over the render cap.
+  // The envelope is a visual approximation that preserves peaks at the cost of
+  // exact per-sample values; the table is the faithful textual representation of
+  // the underlying signal, which is the more useful accessible equivalent. The
+  // two intentionally differ for long buffers — the table is not a row-for-row
+  // transcript of the rendered path.
+  const TABLE_SAMPLE_LIMIT = 20;
+  const isTableSampled = $derived(data.length > TABLE_SAMPLE_LIMIT);
+  const tableSamples = $derived.by(() => {
+    if (data.length === 0) return [];
+    const step = Math.max(1, Math.ceil(data.length / TABLE_SAMPLE_LIMIT));
+    const out: { index: number; value: number }[] = [];
+    for (let index = 0; index < data.length; index += step) {
+      out.push({ index, value: clampSample(data[index]) });
+    }
+    return out;
+  });
+  const tableCaption = $derived.by(() => {
+    const base = dataTableCaption ?? label;
+    if (!isTableSampled) return base;
+    return `${base} (${tableSamples.length} of ${data.length} samples shown)`;
+  });
+</script>
+
+<figure
+  {...rest}
+  bind:this={rootElement}
+  id={rootId}
+  class={classNames('cinder-waveform', customClassName)}
+  aria-label={label}
+  aria-describedby={descriptionId}
+  data-cinder-render-mode={renderMode}
+>
+  {#if description}
+    <p id={descriptionId} class="cinder-waveform__description">{description}</p>
+  {/if}
+  <div
+    class="cinder-waveform__viewport"
+    style:height="{height}px"
+    data-cinder-loading={loading || undefined}
+  >
+    {#if loading}
+      <div class="cinder-waveform__state">
+        {#if loadingContent}{@render loadingContent()}{:else}Loading…{/if}
+      </div>
+    {:else if isEmpty}
+      <div class="cinder-waveform__state">
+        {#if empty}{@render empty()}{:else}No waveform 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}
+      {#if !loading && !isEmpty}
+        <!-- Center baseline -->
+        <line
+          class="cinder-waveform__baseline"
+          x1="0"
+          x2={measuredWidth}
+          y1={midY}
+          y2={midY}
+          aria-hidden="true"
+        />
+        {#if renderMode === 'bars'}
+          {#each waveformBars as bar, index (index)}
+            <rect
+              class="cinder-waveform__bar"
+              x={bar.x}
+              y={bar.y}
+              width={bar.width}
+              height={bar.height}
+              aria-hidden="true"
+            />
+          {/each}
+        {:else}
+          <path class="cinder-waveform__path" d={waveformPath} aria-hidden="true" />
+        {/if}
+      {/if}
+    </svg>
+  </div>
+  {#if hasDataTable}
+    <table class={dataTableClass(dataTableVisibility)}>
+      <caption>{tableCaption}</caption>
+      <thead>
+        <tr>
+          <th scope="col">Sample index</th>
+          <th scope="col">Amplitude</th>
+        </tr>
+      </thead>
+      <tbody>
+        {#each tableSamples as sample (sample.index)}
+          <tr>
+            <td>{sample.index}</td>
+            <td>{sample.value.toFixed(4)}</td>
+          </tr>
+        {/each}
+      </tbody>
+    </table>
+  {/if}
+</figure>

package/src/components/waveform/waveform.types.ts

@@ -0,0 +1,45 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ChartDataTableVisibility } from '../chart.types.ts';
+
+export type WaveformRenderMode = 'path' | 'bars';
+
+export type WaveformProps = Omit<HTMLAttributes<HTMLElement>, 'class'> & {
+  /** Accessible label for the waveform. Required for screen readers. */
+  label: string;
+  /** Optional description rendered below the label. */
+  description?: string;
+  /**
+   * Time-domain amplitude samples. Each value should be in the range [-1, 1].
+   * Values outside this range are clamped.
+   */
+  data: number[];
+  /** How to render the waveform: as a continuous path or vertical amplitude bars. Default `path`. */
+  renderMode?: WaveformRenderMode;
+  /** Pixel height of the chart. Default `80`. */
+  height?: number;
+  /** Whether the waveform 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 the chart has no data. */
+  empty?: Snippet;
+  /** Snippet rendered while loading. */
+  loadingContent?: Snippet;
+};
+
+export type WaveformSchemaProps = {
+  label: string;
+  description?: string;
+  data: number[];
+  renderMode?: WaveformRenderMode;
+  height?: number;
+  loading?: boolean;
+  dataTableVisibility?: ChartDataTableVisibility;
+  dataTableCaption?: string;
+  class?: string;
+};

package/src/components/waveform/waveform.variables.json

@@ -0,0 +1 @@
+[]

package/src/components/waveform/waveform.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/index.ts

@@ -89,11 +89,22 @@ export { default as Callout } from './components/callout/index.ts';
 export type { CalloutProps, CalloutVariant } from './components/callout/index.ts';
 
 export { default as Card } from './components/card/index.ts';
-export type { CardProps, CardTone, CardVariant } from './components/card/index.ts';
+export type { CardPadding, CardProps, CardTone, CardVariant } from './components/card/index.ts';
 
 export { default as Chat } from './components/chat/index.ts';
 export type { ChatProps } from './components/chat/index.ts';
 
+export { default as ChoiceGrid } from './components/choice-grid/index.ts';
+export type {
+  ChoiceGridColumns,
+  ChoiceGridContext,
+  ChoiceGridItemState,
+  ChoiceGridProps,
+} from './components/choice-grid/index.ts';
+
+export { default as ChoiceGridItem } from './components/choice-grid-item/index.ts';
+export type { ChoiceGridItemProps } from './components/choice-grid-item/index.ts';
+
 export { default as Chip } from './components/chip/index.ts';
 export type {
   ChipDensity,
@@ -180,6 +191,13 @@ export { copyToClipboard } from './utilities/clipboard.ts';
 export { default as DataList } from './components/data-list/index.ts';
 export type { DataListProps } from './components/data-list/index.ts';
 
+export { default as DataTable } from './components/data-table/index.ts';
+export type {
+  DataTableColumn,
+  DataTableProps,
+  DataTableRow,
+} from './components/data-table/index.ts';
+
 export { default as DescriptionList } from './components/description-list/index.ts';
 export type {
   DescriptionListItem,
@@ -215,7 +233,12 @@ export type {
 } from './components/dropdown/index.ts';
 
 export { default as DropdownItem } from './components/dropdown-item/index.ts';
-export type { DropdownItemProps, DropdownItemVariant } from './components/dropdown-item/index.ts';
+export type {
+  DropdownItemAnchorProps,
+  DropdownItemButtonProps,
+  DropdownItemProps,
+  DropdownItemVariant,
+} from './components/dropdown-item/index.ts';
 
 export { default as DropdownGroup } from './components/dropdown-group/index.ts';
 export type { DropdownGroupProps } from './components/dropdown-group/index.ts';
@@ -303,6 +326,13 @@ export type {
 export { default as JsonViewer } from './components/json-viewer/index.ts';
 export type { JsonViewerProps } from './components/json-viewer/index.ts';
 
+export { default as CapabilityGate } from './components/capability-gate/index.ts';
+export type {
+  CapabilityGateProps,
+  CapabilityGateState,
+  CapabilityGateVariant,
+} from './components/capability-gate/index.ts';
+
 export { default as KanbanBoard } from './components/kanban-board/index.ts';
 export type {
   KanbanBoardCardContext,
@@ -318,6 +348,13 @@ export type {
 export { default as Kbd } from './components/kbd/index.ts';
 export type { KbdProps } from './components/kbd/index.ts';
 
+export { default as KeyboardShortcuts } from './components/keyboard-shortcuts/index.ts';
+export type {
+  KeyboardShortcutEntry,
+  KeyboardShortcutGroup,
+  KeyboardShortcutsProps,
+} from './components/keyboard-shortcuts/index.ts';
+
 export { default as Label } from './components/label/index.ts';
 export type { LabelProps } from './components/label/index.ts';
 
@@ -330,6 +367,9 @@ export type { LineChartProps, LineChartSchemaProps } from './components/line-cha
 export { default as LoadMore } from './components/load-more/index.ts';
 export type { LoadMoreProps } from './components/load-more/index.ts';
 
+export { default as MediaControls } from './components/media-controls/index.ts';
+export type { MediaControlsLayout, MediaControlsProps } from './components/media-controls/index.ts';
+
 export { default as MarkdownEditor } from './components/markdown-editor/index.ts';
 export type {
   EditorHandle,
@@ -354,6 +394,10 @@ export type {
 export { default as Message } from './components/message/index.ts';
 export type { MessageProps, MessageRole } from './components/message/index.ts';
 
+export { default as MatrixChart } from './components/matrix-chart/index.ts';
+export type { MatrixChartProps, MatrixChartSchemaProps } from './components/matrix-chart/index.ts';
+export type { MatrixColorScale } from './components/matrix-chart/matrix-chart.types.ts';
+
 export { default as Modal } from './components/modal/index.ts';
 export type { ModalProps } from './components/modal/index.ts';
 
@@ -391,6 +435,9 @@ export type { PinInputMode, PinInputProps } from './components/pin-input/index.t
 export { default as Popover } from './components/popover/index.ts';
 export type { PopoverPlacement, PopoverProps, PopoverRole } from './components/popover/index.ts';
 
+export { default as PricingCard } from './components/pricing-card/index.ts';
+export type { PricingCardProps } from './components/pricing-card/index.ts';
+
 export { default as Progress } from './components/progress/index.ts';
 export type { ProgressProps, ProgressSize, ProgressVariant } from './components/progress/index.ts';
 
@@ -476,9 +523,15 @@ export type {
   SelectionPopoverProps,
 } from './components/selection-popover/index.ts';
 
+export { default as ShareCard } from './components/share-card/index.ts';
+export type { ShareCardAction, ShareCardProps } from './components/share-card/index.ts';
+
 export { default as Sheet } from './components/sheet/index.ts';
 export type { SheetProps } from './components/sheet/index.ts';
 
+export { default as ShortcutHint } from './components/shortcut-hint/index.ts';
+export type { ShortcutHintProps } from './components/shortcut-hint/index.ts';
+
 export { default as SideNavigation } from './components/side-navigation/index.ts';
 export type { SideNavigationProps } from './components/side-navigation/index.ts';
 
@@ -502,6 +555,9 @@ export type {
 export { default as Skeleton } from './components/skeleton/index.ts';
 export type { SkeletonProps } from './components/skeleton/index.ts';
 
+export { default as SkipLink } from './components/skip-link/index.ts';
+export type { SkipLinkProps, SkipLinkSchemaProps } from './components/skip-link/index.ts';
+
 export { default as Slider } from './components/slider/index.ts';
 export type { SliderMode, SliderProps, SliderValue } from './components/slider/index.ts';
 
@@ -511,6 +567,20 @@ export type {
   StackedListItemProps,
 } from './components/stacked-list-item/index.ts';
 
+export { default as Spectrogram } from './components/spectrogram/index.ts';
+export type {
+  SpectrogramFrame,
+  SpectrogramProps,
+  SpectrogramSchemaProps,
+} from './components/spectrogram/index.ts';
+
+export { default as SpectrumChart } from './components/spectrum-chart/index.ts';
+export type {
+  SpectrumBin,
+  SpectrumChartProps,
+  SpectrumChartSchemaProps,
+} from './components/spectrum-chart/index.ts';
+
 export { default as Spinner } from './components/spinner/index.ts';
 export type { SpinnerProps, SpinnerSize } from './components/spinner/index.ts';
 
@@ -534,6 +604,12 @@ export type {
   StatusDotStatus,
 } from './components/status-dot/index.ts';
 
+export { default as SubscriptionBadge } from './components/subscription-badge/index.ts';
+export type {
+  SubscriptionBadgeProps,
+  SubscriptionState,
+} from './components/subscription-badge/index.ts';
+
 export { default as Surface } from './components/surface/index.ts';
 export type { SurfaceProps, SurfaceTone } from './components/surface/index.ts';
 
@@ -655,3 +731,10 @@ export type {
   VisuallyHiddenElement,
   VisuallyHiddenProps,
 } from './components/visually-hidden/index.ts';
+
+export { default as Waveform } from './components/waveform/index.ts';
+export type {
+  WaveformProps,
+  WaveformRenderMode,
+  WaveformSchemaProps,
+} from './components/waveform/index.ts';

package/src/styles/components.css

@@ -26,7 +26,9 @@
 @import '../components/button-group/button-group.css';
 @import '../components/callout/callout.css';
 @import '../components/card/card.css';
+@import '../components/capability-gate/capability-gate.css';
 @import '../components/chip/chip.css';
+@import '../components/choice-grid/choice-grid.css';
 @import '../components/checkbox/checkbox.css';
 @import '../components/checkbox-group/checkbox-group.css';
 @import '../components/code-block/code-block.css';
@@ -42,6 +44,7 @@
 @import '../components/context-menu/context-menu.css';
 @import '../components/copy-button/copy-button.css';
 @import '../components/data-list/data-list.css';
+@import '../components/data-table/data-table.css';
 @import '../components/description-list/description-list.css';
 @import '../components/diff-statistics/diff-statistics.css';
 @import '../components/divider/divider.css';
@@ -63,10 +66,13 @@
 @import '../components/json-viewer/json-viewer.css';
 @import '../components/kanban-board/kanban-board.css';
 @import '../components/kbd/kbd.css';
+@import '../components/keyboard-shortcuts/keyboard-shortcuts.css';
 @import '../components/label/label.css';
 @import '../components/line-chart/line-chart.css';
 @import '../components/link/link.css';
+@import '../components/matrix-chart/matrix-chart.css';
 @import '../components/load-more/load-more.css';
+@import '../components/media-controls/media-controls.css';
 @import '../components/menu-bar/menu-bar.css';
 @import '../components/message/message.css';
 @import '../components/modal/modal.css';
@@ -77,6 +83,7 @@
 @import '../components/phone-input/phone-input.css';
 @import '../components/pin-input/pin-input.css';
 @import '../components/popover/popover.css';
+@import '../components/pricing-card/pricing-card.css';
 @import '../components/progress/progress.css';
 @import '../components/_radio/radio.css';
 @import '../components/radio-group/radio-group.css';
@@ -85,13 +92,17 @@
 @import '../components/review-editor/review-editor.css';
 @import '../components/scroll-area/scroll-area.css';
 @import '../components/search-field/search-field.css';
+@import '../components/share-card/share-card.css';
 @import '../components/section-heading/section-heading.css';
 @import '../components/select/select.css';
 @import '../components/segmented-control/segmented-control.css';
 @import '../components/selection-popover/selection-popover.css';
+@import '../components/spectrogram/spectrogram.css';
+@import '../components/spectrum-chart/spectrum-chart.css';
 @import '../components/side-navigation/side-navigation.css';
 @import '../components/side-navigation-group/side-navigation-group.css';
 @import '../components/sheet/sheet.css';
+@import '../components/shortcut-hint/shortcut-hint.css';
 @import '../components/sidebar/sidebar.css';
 @import '../components/skeleton/skeleton.css';
 @import '../components/slider/slider.css';
@@ -102,6 +113,7 @@
 @import '../components/stat-group/stat-group.css';
 @import '../components/status-dot/status-dot.css';
 @import '../components/steps/steps.css';
+@import '../components/subscription-badge/subscription-badge.css';
 @import '../components/surface/surface.css';
 @import '../components/tab/tab.css';
 @import '../components/tab-list/tab-list.css';
@@ -124,6 +136,7 @@
 @import '../components/tree/tree.css';
 @import '../components/_tree-select-all/tree-select-all.css';
 @import '../components/typography/typography.css';
+@import '../components/waveform/waveform.css';
 
 /* Shared internal partial — base chrome for Alert/Banner dismiss buttons.
  * Imported last to preserve the original source order of the inline rule it

package/src/styles/shell.css

@@ -8,8 +8,11 @@
 
 @import './index.css';
 @import '../components/button/button.css';
+@import '../components/color-picker/color-picker.css';
+@import '../components/color-swatch-picker/color-swatch-picker.css';
 @import '../components/input/input.css';
 @import '../components/number-input/number-input.css';
+@import '../components/popover/popover.css';
 @import '../components/segmented-control/segmented-control.css';
 @import '../components/side-navigation/side-navigation.css';
 /* side-navigation.css intentionally carries no per-item styling — the row