docs: add JSDoc and tests for hooks (svelteplot#368)

## Summary
- Add JSDoc documentation to all exported functions and classes in
`plotDefaults.ts` and `usePlot.svelte.ts`
- Add 8 unit tests covering `setPlotDefaults`/`getPlotDefaults` (context
merging, override behavior) and `usePlot`/`setPlot` (state access via
Plot component context)
- Test wrapper components follow the existing pattern from
`src/tests/plot.test.svelte`

## Test plan
- [x] All 8 new hook tests pass (`pnpm run test:unit`)
- [x] All 451 existing tests still pass
- [x] Prettier and ESLint pass (`pnpm run lint`)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 <[email protected]>
Co-authored-by: Gregor Aisch <[email protected]>

Author: 3 people

src/lib/hooks/plotDefaults.test.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+    import { setPlotDefaults, getPlotDefaults } from './plotDefaults.js';
+    import type { PlotDefaults } from 'svelteplot/types';
+
+    let {
+        defaults = {}
+    }: {
+        defaults?: Partial<PlotDefaults>;
+    } = $props();
+
+    setPlotDefaults(defaults);
+
+    const result = getPlotDefaults();
+</script>
+
+<div data-testid="defaults" data-defaults={JSON.stringify(result)}></div>

src/lib/hooks/plotDefaults.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/svelte';
+import PlotDefaultsTest from './plotDefaults.test.svelte';
+import PlotDefaultsNestedTest from './plotDefaultsNested.test.svelte';
+
+function getDefaults(container: HTMLElement) {
+    const el = container.querySelector('[data-testid="defaults"]')!;
+    return JSON.parse(el.getAttribute('data-defaults')!);
+}
+
+describe('plotDefaults', () => {
+    it('getPlotDefaults returns empty object when no defaults set', () => {
+        const { container } = render(PlotDefaultsTest, {
+            props: { defaults: {} }
+        });
+        expect(getDefaults(container)).toEqual({});
+    });
+
+    it('setPlotDefaults makes values available via getPlotDefaults', () => {
+        const { container } = render(PlotDefaultsTest, {
+            props: { defaults: { height: 200 } }
+        });
+        expect(getDefaults(container)).toEqual({
+            height: 200
+        });
+    });
+
+    it('setPlotDefaults merges with existing defaults', () => {
+        const { container } = render(PlotDefaultsNestedTest, {
+            props: {
+                parentDefaults: { height: 200 },
+                childDefaults: { inset: 5 }
+            }
+        });
+        expect(getDefaults(container)).toEqual({
+            height: 200,
+            inset: 5
+        });
+    });
+
+    it('later defaults override earlier ones for same key', () => {
+        const { container } = render(PlotDefaultsNestedTest, {
+            props: {
+                parentDefaults: { height: 200 },
+                childDefaults: { height: 300 }
+            }
+        });
+        expect(getDefaults(container)).toEqual({
+            height: 300
+        });
+    });
+});

src/lib/hooks/plotDefaults.ts

@@ -3,12 +3,14 @@ import type { PlotDefaults } from 'svelteplot/types';
 
 const PLOT_DEFAULTS_KEY = Symbol('svelteplot/defaults');
 
+/** sets default options for all Plot components in this component tree, merging with any existing defaults from parent contexts */
 export function setPlotDefaults(plotDefaults: Partial<PlotDefaults>) {
     const existingDefaults = getPlotDefaults();
     const mergedDefaults = { ...existingDefaults, ...plotDefaults };
     setContext(PLOT_DEFAULTS_KEY, mergedDefaults);
 }
 
+/** retrieves the current plot defaults from the Svelte context, or an empty object if none have been set */
 export function getPlotDefaults(): Partial<PlotDefaults> {
     return hasContext(PLOT_DEFAULTS_KEY)
         ? getContext<PlotDefaults>(PLOT_DEFAULTS_KEY)

src/lib/hooks/plotDefaultsNested.test.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+    import { setPlotDefaults, getPlotDefaults } from './plotDefaults.js';
+    import type { PlotDefaults } from 'svelteplot/types';
+
+    let {
+        parentDefaults = {},
+        childDefaults = {}
+    }: {
+        parentDefaults?: Partial<PlotDefaults>;
+        childDefaults?: Partial<PlotDefaults>;
+    } = $props();
+
+    setPlotDefaults(parentDefaults);
+    setPlotDefaults(childDefaults);
+
+    const result = getPlotDefaults();
+</script>
+
+<div data-testid="defaults" data-defaults={JSON.stringify(result)}></div>

src/lib/hooks/usePlot.svelte.ts

@@ -3,10 +3,9 @@ import type { PlotContext, PlotOptions } from 'svelteplot/types/plot';
 import type { PlotScales, PlotState as TPlotState } from 'svelteplot/types';
 
 /**
- * Internal state representation of a Plot.
+ * internal state representation of a Plot, using Svelte 5 runes for reactivity
  */
 class PlotState implements TPlotState {
-    // Define properties and methods for PlotState as needed
     width: number = $state(50);
     height: number = $state(50);
     options: PlotOptions = $state({});
@@ -32,18 +31,18 @@ class PlotState implements TPlotState {
         Object.assign(this, state);
     }
 
+    /** merges partial state into the current plot state */
     update(newState: Partial<PlotState>) {
         Object.assign(this, newState);
     }
 
+    /** returns a read-only wrapper exposing only public properties */
     get publicState() {
         return new PublicPlotState(this);
     }
 }
 
-/**
- * A public-facing wrapper around PlotState that exposes only read-only properties.
- */
+/** read-only wrapper around PlotState that exposes only getter properties */
 class PublicPlotState {
     #plotState: PlotState;
     constructor(plotState: PlotState) {
@@ -88,12 +87,14 @@ class PublicPlotState {
     }
 }
 
+/** creates a new PlotState instance from the given initial state */
 export function setPlot(initialState: PlotState): PlotState {
     return new PlotState({
         ...initialState
     });
 }
 
+/** returns the current Plot's public state from Svelte context. Must be called within a `<Plot>` component tree. */
 export function usePlot(): Readonly<TPlotState> {
     const { getPlotState } = getContext<PlotContext>('svelteplot');
     return getPlotState().publicState;

src/lib/hooks/usePlot.test.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+    import { Plot } from '$lib/index.js';
+    import UsePlotChild from './usePlotChild.test.svelte';
+
+    let { width = 100, height = 100 }: { width?: number; height?: number } = $props();
+</script>
+
+<Plot {width} {height}>
+    <UsePlotChild />
+</Plot>

src/lib/hooks/usePlot.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/svelte';
+import UsePlotTest from './usePlot.test.svelte';
+
+describe('usePlot', () => {
+    it('returns plot state with correct height', () => {
+        const { container } = render(UsePlotTest, {
+            props: { width: 200, height: 150 }
+        });
+        const el = container.querySelector('[data-testid="plot-state"]')!;
+        expect(el.getAttribute('data-height')).toBe('150');
+    });
+
+    it('returns default dimensions when no props given', () => {
+        const { container } = render(UsePlotTest);
+        const el = container.querySelector('[data-testid="plot-state"]')!;
+        expect(el.getAttribute('data-height')).toBe('100');
+    });
+
+    it('exposes plotWidth and plotHeight', () => {
+        const { container } = render(UsePlotTest, {
+            props: { width: 100, height: 100 }
+        });
+        const el = container.querySelector('[data-testid="plot-state"]')!;
+        // plotWidth/plotHeight are width/height minus margins
+        const plotWidth = Number(el.getAttribute('data-plot-width'));
+        const plotHeight = Number(el.getAttribute('data-plot-height'));
+        expect(plotWidth).toBeGreaterThan(0);
+        expect(plotWidth).toBeLessThanOrEqual(100);
+        expect(plotHeight).toBeGreaterThan(0);
+        expect(plotHeight).toBeLessThanOrEqual(100);
+    });
+});
+
+describe('setPlot', () => {
+    it('creates PlotState used by Plot component', () => {
+        // setPlot is called internally by Plot, so we verify
+        // it works indirectly through usePlot
+        const { container } = render(UsePlotTest, {
+            props: { width: 300, height: 250 }
+        });
+        const el = container.querySelector('[data-testid="plot-state"]')!;
+        expect(el.getAttribute('data-height')).toBe('250');
+    });
+});

src/lib/hooks/usePlotChild.test.svelte

@@ -0,0 +1,13 @@
+<script lang="ts">
+    import { usePlot } from './usePlot.svelte.js';
+
+    const plot = usePlot();
+</script>
+
+<div
+    data-testid="plot-state"
+    data-width={plot.width}
+    data-height={plot.height}
+    data-plot-width={plot.plotWidth}
+    data-plot-height={plot.plotHeight}>
+</div>