@lostgradient/cinder 0.1.0 → 0.2.0

package/src/components/shortcut-hint/shortcut-hint.types.ts

@@ -0,0 +1,35 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+/** Props for the ShortcutHint component. */
+export type ShortcutHintProps = Omit<HTMLAttributes<HTMLSpanElement>, 'class' | 'children'> & {
+  /** The key sequence to display (e.g. ["Ctrl", "S"] or ["Space"]). */
+  keys: string[];
+  /** Optional accessible label for the key combo. Defaults to joining keys with " plus ". */
+  keysLabel?: string;
+  /** The action or label to render alongside the key combo. */
+  children?: Snippet;
+  /** Whether to place the keys before or after the children. @default "after" */
+  keysPosition?: 'before' | 'after';
+  /** Additional class names merged with `.cinder-shortcut-hint`. */
+  class?: string;
+};
+
+/**
+ * Cinder-specific props for ShortcutHint, used by the schema generator.
+ */
+export interface ShortcutHintSchemaProps {
+  /** The key sequence to display. */
+  keys: string[];
+  /** Accessible label for the key combo. */
+  keysLabel?: string;
+  /**
+   * Position of keys relative to children.
+   * @default "after"
+   */
+  keysPosition?: 'before' | 'after';
+  /** Additional class names merged with `.cinder-shortcut-hint`. */
+  class?: string;
+  /** The action label rendered beside the keys. */
+  children?: Snippet;
+}

package/src/components/shortcut-hint/shortcut-hint.variables.json

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

package/src/components/shortcut-hint/shortcut-hint.variables.ts

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

package/src/components/side-navigation/side-navigation.examples.json

@@ -8,6 +8,12 @@
       "title": "Basic side navigation",
       "description": "A grouped sidebar nav. Uses the SideNavigation namespace API: SideNavigation.Group wraps a collapsible section and SideNavigation.Item renders each link.",
       "code": "<script lang=\"ts\">\n  import { SideNavigation } from '@lostgradient/cinder/side-navigation';\n</script>\n\n<SideNavigation ariaLabel=\"Workspace\">\n  <SideNavigation.Item href=\"/dashboard\">Dashboard</SideNavigation.Item>\n  <SideNavigation.Group label=\"Projects\">\n    <SideNavigation.Item href=\"/projects/phoenix\" active>Phoenix</SideNavigation.Item>\n    <SideNavigation.Item href=\"/projects/atlas\">Atlas</SideNavigation.Item>\n    <SideNavigation.Item href=\"/projects/beacon\">Beacon</SideNavigation.Item>\n  </SideNavigation.Group>\n  <SideNavigation.Group label=\"Settings\">\n    <SideNavigation.Item href=\"/settings/team\">Team</SideNavigation.Item>\n    <SideNavigation.Item href=\"/settings/billing\">Billing</SideNavigation.Item>\n  </SideNavigation.Group>\n</SideNavigation>\n"
+    },
+    {
+      "id": "docs-sidebar",
+      "title": "Docs sidebar",
+      "description": "Documentation sidebar with grouped navigation sections. The active item receives aria-current=\"page\". ",
+      "code": "<script lang=\"ts\" module>\n  export const title = 'Docs sidebar';\n  export const description =\n    'Documentation sidebar with grouped navigation sections. The active item receives aria-current=\"page\". ' +\n    'Composed inside Sidebar so the column collapses to a drawer below the ~767px viewport breakpoint — ' +\n    'resize your browser window to see the mobile drawer behavior.';\n</script>\n\n<script lang=\"ts\">\n  import { Button } from '@lostgradient/cinder/button';\n  import { SideNavigation } from '@lostgradient/cinder/side-navigation';\n  import { Sidebar } from '@lostgradient/cinder/sidebar';\n\n  let collapsed = $state(false);\n</script>\n\n<div style=\"display: flex; flex-direction: column; gap: 1rem;\">\n  <div>\n    <Button\n      label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}\n      onclick={() => (collapsed = !collapsed)}\n    />\n  </div>\n\n  <div\n    style=\"display: flex; min-height: 28rem; border: 1px solid var(--cinder-border); border-radius: 0.5rem; overflow: hidden;\"\n  >\n    <Sidebar bind:collapsed ariaLabel=\"Documentation\">\n      {#snippet brand()}\n        <strong style=\"font-size: 0.875rem;\">Cinder Docs</strong>\n      {/snippet}\n\n      {#snippet navigation()}\n        <SideNavigation ariaLabel=\"Documentation sections\">\n          <SideNavigation.Group label=\"Getting Started\">\n            <SideNavigation.Item href=\"#introduction\" active>Introduction</SideNavigation.Item>\n            <SideNavigation.Item href=\"#installation\">Installation</SideNavigation.Item>\n            <SideNavigation.Item href=\"#quick-start\">Quick start</SideNavigation.Item>\n          </SideNavigation.Group>\n          <SideNavigation.Group label=\"Components\">\n            <SideNavigation.Item href=\"#button\">Button</SideNavigation.Item>\n            <SideNavigation.Item href=\"#form-section\">FormSection</SideNavigation.Item>\n            <SideNavigation.Item href=\"#side-navigation\">SideNavigation</SideNavigation.Item>\n          </SideNavigation.Group>\n          <SideNavigation.Group label=\"API Reference\">\n            <SideNavigation.Item href=\"#props\">Props</SideNavigation.Item>\n            <SideNavigation.Item href=\"#types\">Types</SideNavigation.Item>\n            <SideNavigation.Item href=\"#css-variables\">CSS variables</SideNavigation.Item>\n          </SideNavigation.Group>\n        </SideNavigation>\n      {/snippet}\n    </Sidebar>\n\n    <main style=\"flex: 1; padding: 1.5rem;\">\n      <p style=\"margin: 0; color: var(--cinder-text-muted); font-size: var(--cinder-text-sm);\">\n        Main content area. Resize the browser viewport below ~767px to see the navigation collapse\n        into a mobile drawer.\n      </p>\n    </main>\n  </div>\n</div>\n"
     }
   ]
 }

package/src/components/skip-link/README.md

@@ -0,0 +1,50 @@
+# SkipLink
+
+A visually hidden skip-to-content link that becomes visible on keyboard focus and moves focus (and the viewport) to a landmark element, letting keyboard and screen-reader users bypass repeated navigation (WCAG 2.4.1 Bypass Blocks).
+
+## Usage
+
+Place it as the first focusable element in your layout and point `target` at the `id` of your main content region.
+
+```svelte
+<script lang="ts">
+  import SkipLink from '@lostgradient/cinder/skip-link';
+</script>
+
+<SkipLink target="main-content">Skip to main content</SkipLink>
+
+<!-- … site navigation … -->
+
+<main id="main-content">
+  <!-- … -->
+</main>
+```
+
+The default label is "Skip to main content"; pass children to override it. SkipLink handles `prefers-reduced-motion` and the tabindex save/restore dance internally, so the target is never left permanently focusable.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop     | Type     | Required | Default | Description                                                          |
+| -------- | -------- | -------- | ------- | -------------------------------------------------------------------- |
+| `class`  | `string` | no       | —       | Additional classes merged onto the visually-hidden anchor.           |
+| `target` | `string` | yes      | —       | The `id` of the element to receive focus when the link is activated. |
+
+<!-- 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/skip-link/index.ts

@@ -0,0 +1,5 @@
+import SkipLink from './skip-link.svelte';
+
+export default SkipLink;
+export type { SkipLinkProps, SkipLinkSchemaProps } from './skip-link.types.ts';
+export { SkipLink };

package/src/components/skip-link/skip-link.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "skip-link",
+  "import": "@lostgradient/cinder/skip-link",
+  "examples": [
+    {
+      "id": "basic",
+      "title": "Basic usage",
+      "description": "Tab into this example to reveal the skip link, then press Enter to jump focus to the main content area.",
+      "code": "<script lang=\"ts\">\n  import { SkipLink } from '@lostgradient/cinder/skip-link';\n</script>\n\n<div\n  style=\"position: relative; min-height: 80px; border: 1px dashed var(--cinder-border); border-radius: 4px; padding: 1rem;\"\n>\n  <SkipLink target=\"skip-link-example-main\" />\n\n  <nav aria-label=\"Example navigation\">\n    <a href=\"#skip-link-example-main\" style=\"margin-right: 1rem;\">Home</a>\n    <a href=\"#skip-link-example-main\" style=\"margin-right: 1rem;\">About</a>\n    <a href=\"#skip-link-example-main\">Contact</a>\n  </nav>\n\n  <main id=\"skip-link-example-main\" style=\"margin-top: 1rem;\">\n    <p>Main content area. Focus lands here when the skip link is activated.</p>\n  </main>\n</div>\n"
+    }
+  ]
+}

package/src/components/skip-link/skip-link.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "target": {
+      "type": "string",
+      "description": "The `id` of the element to receive focus when the link is activated."
+    },
+    "class": {
+      "type": "string",
+      "description": "Additional classes merged onto the visually-hidden anchor."
+    }
+  },
+  "additionalProperties": false,
+  "required": ["target"]
+}

package/src/components/skip-link/skip-link.schema.ts

@@ -0,0 +1,20 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    target: {
+      type: 'string',
+      description: 'The `id` of the element to receive focus when the link is activated.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional classes merged onto the visually-hidden anchor.',
+    },
+  },
+  additionalProperties: false,
+  required: ['target'],
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/skip-link/skip-link.svelte

@@ -0,0 +1,86 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category navigation
+   * @status stable
+   * @purpose Visually hidden skip link that moves keyboard focus to a landmark element, letting keyboard and screen reader users bypass repeated navigation.
+   * @tag navigation
+   * @tag accessibility
+   * @tag skip-link
+   * @useWhen Providing a keyboard shortcut to jump past site-wide navigation directly to the main content area.
+   * @useWhen Meeting WCAG 2.4.1 (Bypass Blocks) without adding visible chrome to the layout.
+   * @avoidWhen The page has no repeated navigation block — a skip link adds no value on single-panel layouts.
+   * @avoidWhen The target region already receives focus naturally without intervention.
+   * @related visually-hidden
+   */
+  export type { SkipLinkProps } from './skip-link.types.ts';
+</script>
+
+<script lang="ts">
+  import { classNames } from '../../utilities/class-names.ts';
+  import { useReducedMotion } from '../../utilities/use-reduced-motion.svelte.ts';
+  import VisuallyHidden from '../visually-hidden/visually-hidden.svelte';
+
+  import type { SkipLinkProps } from './skip-link.types.ts';
+
+  let { target, class: className, children }: SkipLinkProps = $props();
+
+  const motion = useReducedMotion();
+
+  const mergedClass = $derived(classNames(className));
+
+  // Marks a target whose tabindex SkipLink is currently managing, so re-activating
+  // before focus leaves does not recapture the temporary `-1` as the "original"
+  // value or stack a second restore listener.
+  const MANAGED_ATTRIBUTE = 'data-cinder-skip-link-managed';
+
+  function handleClick(event: MouseEvent) {
+    const element = document.getElementById(target);
+
+    if (!element) {
+      // No matching element — let the native anchor jump happen.
+      return;
+    }
+
+    event.preventDefault();
+
+    const alreadyManaged = element.hasAttribute(MANAGED_ATTRIBUTE);
+
+    if (!alreadyManaged) {
+      // First activation: capture the genuine original tabindex, mark the
+      // element as managed, and arm a one-shot restore on the next blur.
+      const originalTabIndex = element.getAttribute('tabindex');
+      element.setAttribute(MANAGED_ATTRIBUTE, '');
+      element.setAttribute('tabindex', '-1');
+
+      element.addEventListener(
+        'blur',
+        () => {
+          element.removeAttribute(MANAGED_ATTRIBUTE);
+          if (originalTabIndex === null) {
+            element.removeAttribute('tabindex');
+          } else {
+            element.setAttribute('tabindex', originalTabIndex);
+          }
+        },
+        { once: true },
+      );
+    }
+
+    // Focus without the browser's implicit scroll so the reduced-motion-aware
+    // scrollIntoView below is the single, authoritative scroll.
+    element.focus({ preventScroll: true });
+    element.scrollIntoView({
+      behavior: motion.current ? 'auto' : 'smooth',
+      block: 'start',
+    });
+  }
+</script>
+
+<VisuallyHidden as="a" href="#{target}" focusable class={mergedClass} onclick={handleClick}>
+  {#if children}
+    {@render children()}
+  {:else}
+    Skip to main content
+  {/if}
+</VisuallyHidden>

package/src/components/skip-link/skip-link.types.ts

@@ -0,0 +1,40 @@
+import type { Snippet } from 'svelte';
+
+/**
+ * Props for the SkipLink component.
+ *
+ * SkipLink composes over VisuallyHidden using `as="a"` with `focusable` mode.
+ * The `target` prop is the id of the element to scroll and move focus to on
+ * activation; the link's `href` is set to `#${target}` automatically.
+ *
+ * The surface is intentionally minimal — `target`, optional `children`, and
+ * `class`. A skip link is a single-purpose control, so it does NOT forward an
+ * arbitrary HTML-attribute bag: doing so would (a) let a consumer's `onclick`
+ * clobber the internal focus-management handler, and (b) blow VisuallyHidden's
+ * `HTMLAttributes & HTMLAnchorAttributes` props into a "union too complex to
+ * represent" error when spread. This matches the issue's proposed API exactly:
+ * `<SkipLink target="main-content">Skip to main content</SkipLink>`.
+ */
+export type SkipLinkProps = {
+  /**
+   * The `id` of the element to receive focus and scroll into view when the
+   * skip link is activated. Required. The rendered `href` is `#${target}`.
+   */
+  target: string;
+  /** Optional override for the visible label. Defaults to "Skip to main content". */
+  children?: Snippet;
+  /** Additional classes merged onto the visually-hidden anchor. */
+  class?: string;
+};
+
+/**
+ * Cinder-specific props for the SkipLink component, used by the schema generator.
+ */
+export interface SkipLinkSchemaProps {
+  /**
+   * The `id` of the element to receive focus when the link is activated.
+   */
+  target: string;
+  /** Additional classes merged onto the visually-hidden anchor. */
+  class?: string;
+}

package/src/components/skip-link/skip-link.variables.json

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

package/src/components/skip-link/skip-link.variables.ts

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

package/src/components/spectrogram/README.md

@@ -0,0 +1,58 @@
+# Spectrogram
+
+Responsive SVG time × frequency heatmap for visualizing audio spectrogram data.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { Spectrogram } from '@lostgradient/cinder/spectrogram';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Visualizing how frequency content of a signal changes over time (time × frequency heatmap).
+- Displaying pre-computed spectrogram frames from an FFT or short-time Fourier transform.
+
+### Avoid When
+
+- Only a single spectrum snapshot is needed — use spectrum-chart instead.
+- Real-time live audio spectrogram is needed — feed frames as props yourself.
+- A categorical × categorical heatmap without a time axis is needed — use matrix-chart instead.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop                  | Type                                                | Required | Default | Description                                                                                             |
+| --------------------- | --------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------- |
+| `class`               | `string`                                            | no       | —       |                                                                                                         |
+| `dataTableCaption`    | `string`                                            | no       | —       |                                                                                                         |
+| `dataTableVisibility` | `"screen-reader-only"` \| `"visible"` \| `"hidden"` | no       | —       |                                                                                                         |
+| `description`         | `string`                                            | no       | —       |                                                                                                         |
+| `frequencyLabels`     | `string`[]                                          | no       | —       |                                                                                                         |
+| `height`              | `number`                                            | no       | —       |                                                                                                         |
+| `label`               | `string`                                            | yes      | —       |                                                                                                         |
+| `loading`             | `boolean`                                           | no       | —       |                                                                                                         |
+| `frames`              | `(opaque)`                                          | no       | —       | A prop whose shape is not captured by the JSON schema; see the component types for the exact 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/spectrogram/index.ts

@@ -0,0 +1,10 @@
+import './spectrogram.css';
+import Spectrogram from './spectrogram.svelte';
+
+export default Spectrogram;
+export type {
+  SpectrogramFrame,
+  SpectrogramProps,
+  SpectrogramSchemaProps,
+} from './spectrogram.types.ts';
+export { Spectrogram };

package/src/components/spectrogram/spectrogram.css

@@ -0,0 +1,43 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+@layer cinder.components {
+  .cinder-spectrogram {
+    display: grid;
+    gap: var(--cinder-space-3);
+    color: var(--cinder-text);
+  }
+
+  .cinder-spectrogram__description {
+    margin: 0;
+    color: var(--cinder-text-muted);
+    font-size: var(--cinder-text-sm);
+  }
+
+  .cinder-spectrogram__viewport {
+    position: relative;
+  }
+
+  .cinder-spectrogram svg {
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+  }
+
+  .cinder-spectrogram__cell {
+    stroke: none;
+  }
+
+  .cinder-spectrogram__tick-label {
+    fill: var(--cinder-text-muted);
+    font-size: var(--cinder-text-xs);
+  }
+
+  .cinder-spectrogram__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/spectrogram/spectrogram.examples.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "../../schemas/examples.schema.json",
+  "component": "spectrogram",
+  "import": "@lostgradient/cinder/spectrogram",
+  "examples": [
+    {
+      "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.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "label": {
+      "type": "string"
+    },
+    "description": {
+      "type": "string"
+    },
+    "frequencyLabels": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "height": {
+      "type": "number"
+    },
+    "loading": {
+      "type": "boolean"
+    },
+    "dataTableVisibility": {
+      "enum": ["screen-reader-only", "visible", "hidden"]
+    },
+    "dataTableCaption": {
+      "type": "string"
+    },
+    "class": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": false,
+  "required": ["label"],
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "frames",
+        "reason": "unknown-shape"
+      }
+    ]
+  }
+}

package/src/components/spectrogram/spectrogram.schema.ts

@@ -0,0 +1,47 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    label: {
+      type: 'string',
+    },
+    description: {
+      type: 'string',
+    },
+    frequencyLabels: {
+      type: 'array',
+      items: {
+        type: 'string',
+      },
+    },
+    height: {
+      type: 'number',
+    },
+    loading: {
+      type: 'boolean',
+    },
+    dataTableVisibility: {
+      enum: ['screen-reader-only', 'visible', 'hidden'],
+    },
+    dataTableCaption: {
+      type: 'string',
+    },
+    class: {
+      type: 'string',
+    },
+  },
+  additionalProperties: false,
+  required: ['label'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'frames',
+        reason: 'unknown-shape',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;