@cfasim-ui/docs 0.4.5 → 0.4.6

package/charts/_shared/useChartPadding.ts

@@ -3,6 +3,21 @@ import { computed } from "vue";
 /** Vertical space reserved at the top of the chart for inline legend swatches. */
 export const INLINE_LEGEND_HEIGHT = 20;
 
+/**
+ * Extra space added around the chart's standard layout. A number applies
+ * the same amount to all four sides; an object lets you pad sides
+ * independently (e.g. `{ top: 24 }` to make room for annotations above
+ * the plot). Named to match Altair's `padding` (outer view padding).
+ */
+export type ChartPadding =
+  | number
+  | {
+      top?: number;
+      right?: number;
+      bottom?: number;
+      left?: number;
+    };
+
 export interface ChartPaddingOptions {
   title: () => string | undefined;
   xLabel: () => string | undefined;
@@ -10,28 +25,77 @@ export interface ChartPaddingOptions {
   hasInlineLegend: () => boolean;
   width: () => number;
   height: () => number;
+  /** Extra pixels added on top of the standard axis spacing. */
+  extraPadding?: () => ChartPadding | undefined;
+}
+
+function resolvePadding(p: ChartPadding | undefined) {
+  if (p == null) return { top: 0, right: 0, bottom: 0, left: 0 };
+  if (typeof p === "number") return { top: p, right: p, bottom: p, left: p };
+  return {
+    top: p.top ?? 0,
+    right: p.right ?? 0,
+    bottom: p.bottom ?? 0,
+    left: p.left ?? 0,
+  };
 }
 
 /**
  * Computes the standard chart padding (top/right/bottom/left) and the
  * derived inner plotting region (innerW, innerH). Shared by LineChart
  * and BarChart so the axis label spacing and inline legend strip stay
- * consistent.
+ * consistent. `extraPadding` adds extra space outside the plot — useful
+ * for annotations that need to extend past the data area without
+ * clipping.
  */
 export function useChartPadding(opts: ChartPaddingOptions) {
-  const padding = computed(() => ({
-    top:
-      (opts.title() ? 30 : 10) +
-      (opts.hasInlineLegend() ? INLINE_LEGEND_HEIGHT : 0),
-    right: 10,
-    bottom: opts.xLabel() ? 46 : 30,
-    left: opts.yLabel() ? 66 : 50,
-  }));
+  const padding = computed(() => {
+    const extra = resolvePadding(opts.extraPadding?.());
+    return {
+      top:
+        (opts.title() ? 26 : 10) +
+        (opts.hasInlineLegend() ? INLINE_LEGEND_HEIGHT : 0) +
+        extra.top,
+      right: 10 + extra.right,
+      bottom: (opts.xLabel() ? 38 : 30) + extra.bottom,
+      left: (opts.yLabel() ? 56 : 50) + extra.left,
+    };
+  });
+  // Y-center of the inline legend strip. Sits at the top of the padding
+  // band (just below any title), so any user-supplied `extraPadding.top`
+  // becomes empty room between the legend and the plot — useful for
+  // annotations that need to extend above the data area.
+  const legendY = computed(
+    () => (opts.title() ? 26 : 10) + INLINE_LEGEND_HEIGHT / 2,
+  );
   const innerW = computed(
     () => opts.width() - padding.value.left - padding.value.right,
   );
   const innerH = computed(
     () => opts.height() - padding.value.top - padding.value.bottom,
   );
-  return { padding, innerW, innerH };
+  // Pixel-space rect of the plot area. Single source of truth for any
+  // consumer that needs to span the full plot (e.g. rule annotations,
+  // background fills, clip paths).
+  const bounds = computed(() => {
+    const p = padding.value;
+    return {
+      left: p.left,
+      top: p.top,
+      right: p.left + innerW.value,
+      bottom: p.top + innerH.value,
+      width: innerW.value,
+      height: innerH.value,
+    };
+  });
+  return { padding, legendY, innerW, innerH, bounds };
 }
+
+export type ChartBounds = {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+  width: number;
+  height: number;
+};

package/charts/index.ts

@@ -31,3 +31,4 @@ export {
   type ColumnConfig,
   type ColumnWidth,
 } from "./DataTable/DataTable.vue";
+export type { ChartAnnotation } from "./_shared/annotations.js";

package/components/ParamEditor/ParamEditor.md

@@ -0,0 +1,78 @@
+# ParamEditor
+
+A code editor for editing simulation parameters as JSON, TOML, or YAML. Backed by CodeMirror 6 with syntax highlighting. Includes Import, Export, and Apply actions. Apply can also be triggered with `Cmd`/`Ctrl`+`S`, and the editor auto-applies on blur whenever the text parses cleanly and the parsed value differs from the current `value`.
+
+Exported files default to `params-YYYYMMDD-HHMMSS.<ext>` (local-time timestamp captured when Export is clicked). Override the basename with the `filename` prop.
+
+The editor is **lazy-loaded**: the underlying CodeMirror bundle and YAML/TOML parsers are only fetched the first time `<ParamEditor>` mounts, so consumers that never open the editor never pay for it.
+
+Users can switch formats from the dropdown; the editor round-trips the current value through the new format. Apply emits an `apply` event with the parsed value — the parent decides what to do with it (typically merge back into its own parameter state).
+
+## Examples
+
+<script setup>
+import { reactive } from 'vue'
+const params = reactive({ beta: 0.5, gamma: 0.1, population: 10000 })
+function onApply(v) { Object.assign(params, v) }
+const yamlParams = reactive({ beta: 0.5, gamma: 0.1 })
+function onYamlApply(v) { Object.assign(yamlParams, v) }
+</script>
+
+### Basic usage
+
+<ComponentDemo>
+  <div style="width: 100%">
+    <ParamEditor :value="params" @apply="onApply" />
+    <p data-testid="basic-output">beta = {{ params.beta }}</p>
+  </div>
+
+<template #code>
+
+```vue
+<script setup>
+import { reactive } from "vue";
+const params = reactive({ beta: 0.5, gamma: 0.1, population: 10000 });
+function onApply(v) {
+  Object.assign(params, v);
+}
+</script>
+
+<template>
+  <ParamEditor :value="params" @apply="onApply" />
+</template>
+```
+
+  </template>
+</ComponentDemo>
+
+### Starting in a different format
+
+<ComponentDemo>
+  <div style="width: 100%">
+    <ParamEditor :value="yamlParams" format="yaml" @apply="onYamlApply" />
+  </div>
+
+<template #code>
+
+```vue
+<ParamEditor :value="params" format="yaml" @apply="onApply" />
+```
+
+  </template>
+</ComponentDemo>
+
+## Props
+
+| Prop | Type | Required | Default |
+|------|------|----------|---------|
+| `value` | `ParamEditorValue` | Yes | — |
+| `format` | `ParamEditorFormat` | No | — |
+| `height` | `string` | No | — |
+| `filename` | `string` | No | — |
+
+## Events
+
+| Event | Payload |
+|-------|---------|
+| `apply` | `value: ParamEditorValue` |
+

package/components/ParamEditor/ParamEditor.vue

@@ -0,0 +1,39 @@
+<script setup lang="ts">
+import { defineAsyncComponent } from "vue";
+import Spinner from "../Spinner/Spinner.vue";
+
+export type ParamEditorFormat = "json" | "toml" | "yaml";
+export type ParamEditorValue = Record<string, unknown>;
+
+defineProps<{
+  value: ParamEditorValue;
+  format?: ParamEditorFormat;
+  height?: string;
+  /** Basename for the Export download (no extension). Defaults to
+   *  `params-YYYYMMDD-HHMMSS` computed at click time. */
+  filename?: string;
+}>();
+
+defineEmits<{
+  apply: [value: ParamEditorValue];
+}>();
+
+// The actual editor (CodeMirror + YAML/TOML parsers) is loaded on demand
+// the first time this component mounts, so consumers that never open the
+// editor never pay for the ~200KB gzipped of editor + language code.
+const Impl = defineAsyncComponent({
+  loader: () => import("./ParamEditorImpl.vue"),
+  loadingComponent: Spinner,
+  delay: 100,
+});
+</script>
+
+<template>
+  <Impl
+    :value="value"
+    :format="format"
+    :height="height"
+    :filename="filename"
+    @apply="$emit('apply', $event)"
+  />
+</template>

package/components/ParamEditor/ParamEditorImpl.vue

@@ -0,0 +1,355 @@
+<script setup lang="ts">
+import {
+  ref,
+  computed,
+  watch,
+  useTemplateRef,
+  onMounted,
+  onUnmounted,
+} from "vue";
+import { Codemirror } from "vue-codemirror";
+import { json as jsonLang } from "@codemirror/lang-json";
+import { yaml as yamlLang } from "@codemirror/lang-yaml";
+import { StreamLanguage } from "@codemirror/language";
+import { toml as tomlMode } from "@codemirror/legacy-modes/mode/toml";
+import { EditorView, keymap } from "@codemirror/view";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import Box from "../Box/Box.vue";
+import Button from "../Button/Button.vue";
+import SelectBox from "../SelectBox/SelectBox.vue";
+
+type Format = "json" | "toml" | "yaml";
+type Value = Record<string, unknown>;
+
+const props = withDefaults(
+  defineProps<{
+    value: Value;
+    format?: Format;
+    height?: string;
+    filename?: string;
+  }>(),
+  { format: "json", height: "320px" },
+);
+
+const emit = defineEmits<{ apply: [value: Value] }>();
+
+const formatOptions = [
+  { value: "json", label: "JSON" },
+  { value: "toml", label: "TOML" },
+  { value: "yaml", label: "YAML" },
+];
+
+function serialize(v: Value, f: Format): string {
+  if (f === "json") return JSON.stringify(v, null, 2);
+  if (f === "yaml") return stringifyYaml(v);
+  return stringifyToml(v);
+}
+
+function parse(t: string, f: Format): Value {
+  if (f === "json") return JSON.parse(t) as Value;
+  if (f === "yaml") return parseYaml(t) as Value;
+  return parseToml(t) as Value;
+}
+
+const format = ref<Format>(props.format);
+const text = ref(serialize(props.value, format.value));
+const error = ref("");
+
+// Clear a previously-surfaced parse error as soon as the text parses
+// cleanly again, so the user doesn't have to re-trigger Apply just to
+// see the error go away after they fix it.
+watch(text, () => {
+  if (!error.value) return;
+  try {
+    parse(text.value, format.value);
+    error.value = "";
+  } catch {
+    // Still broken — keep the error visible.
+  }
+});
+
+const isMac =
+  typeof navigator !== "undefined" &&
+  /Mac|iPhone|iPad/.test(navigator.platform);
+const applyShortcut = isMac ? "⌘S" : "Ctrl+S";
+
+// External value updates (e.g., parent Reset) re-seed the editor. The
+// inequality check keeps the post-apply re-render a no-op: when the
+// parent absorbs the user's apply, `props.value` re-serializes back
+// to the same string the user just typed, so we leave `text` untouched.
+watch(
+  () => props.value,
+  (v) => {
+    const next = serialize(v, format.value);
+    if (next === text.value) return;
+    text.value = next;
+    error.value = "";
+  },
+  { deep: true },
+);
+
+// Convert text between formats by round-tripping through `parse` →
+// `serialize`. If the current text doesn't parse, we keep the old
+// format and surface the error.
+function onFormatChange(next: string) {
+  const target = next as Format;
+  if (target === format.value) return;
+  try {
+    const parsed = parse(text.value, format.value);
+    text.value = serialize(parsed, target);
+    format.value = target;
+    error.value = "";
+  } catch (e) {
+    error.value = `Cannot switch format: ${(e as Error).message}`;
+  }
+}
+
+function handleApply() {
+  try {
+    const parsed = parse(text.value, format.value);
+    error.value = "";
+    emit("apply", parsed);
+  } catch (e) {
+    error.value = (e as Error).message;
+  }
+}
+
+// Auto-apply when the editor loses focus, but only when the text parses
+// cleanly (we don't want to nag with errors as the user clicks away —
+// they can hit Apply explicitly to see what's wrong) and only when the
+// parsed value actually differs from `props.value`.
+function handleBlur() {
+  let parsed: Value;
+  try {
+    parsed = parse(text.value, format.value);
+  } catch {
+    return;
+  }
+  if (serialize(parsed, format.value) === serialize(props.value, format.value))
+    return;
+  error.value = "";
+  emit("apply", parsed);
+}
+
+// CodeMirror's contenteditable doesn't fire `blur` when the user clicks
+// on a non-focusable element (e.g., empty page area or a chart svg), so
+// we watch document pointerdown for clicks outside our wrapper and
+// trigger the blur-apply logic ourselves.
+const rootRef = useTemplateRef<HTMLElement>("rootRef");
+
+function onDocumentPointerDown(e: PointerEvent) {
+  const target = e.target as Node | null;
+  if (!rootRef.value || !target) return;
+  if (rootRef.value.contains(target)) return;
+  handleBlur();
+}
+
+onMounted(() => {
+  document.addEventListener("pointerdown", onDocumentPointerDown);
+});
+onUnmounted(() => {
+  document.removeEventListener("pointerdown", onDocumentPointerDown);
+});
+
+const extensions = computed(() => [
+  format.value === "json"
+    ? jsonLang()
+    : format.value === "yaml"
+      ? yamlLang()
+      : StreamLanguage.define(tomlMode),
+  EditorView.lineWrapping,
+  // Bind Cmd/Ctrl+S to Apply and stop the browser from intercepting it
+  // for its own "Save page as…" dialog.
+  keymap.of([
+    {
+      key: "Mod-s",
+      preventDefault: true,
+      run: () => {
+        handleApply();
+        return true;
+      },
+    },
+  ]),
+]);
+
+// `YYYYMMDD-HHMMSS` in local time — readable, sortable, and filesystem-safe
+// on Windows (no colons). Computed at export time so the name reflects
+// when the user clicked, not when the editor mounted.
+function defaultFilename(): string {
+  const d = new Date();
+  const pad = (n: number) => n.toString().padStart(2, "0");
+  const ts =
+    `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}` +
+    `-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+  return `params-${ts}`;
+}
+
+function handleExport() {
+  const ext = format.value === "yaml" ? "yml" : format.value;
+  const mime =
+    format.value === "json"
+      ? "application/json"
+      : format.value === "yaml"
+        ? "application/yaml"
+        : "application/toml";
+  const base = props.filename ?? defaultFilename();
+  const blob = new Blob([text.value], { type: mime });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = `${base}.${ext}`;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+const fileInput = useTemplateRef<HTMLInputElement>("fileInput");
+
+function handleImport() {
+  fileInput.value?.click();
+}
+
+function inferFormat(filename: string): Format {
+  const n = filename.toLowerCase();
+  if (n.endsWith(".yaml") || n.endsWith(".yml")) return "yaml";
+  if (n.endsWith(".toml")) return "toml";
+  return "json";
+}
+
+async function onFileChange(e: Event) {
+  const input = e.target as HTMLInputElement;
+  const file = input.files?.[0];
+  if (!file) return;
+  const raw = await file.text();
+  const inferred = inferFormat(file.name);
+  format.value = inferred;
+  text.value = raw;
+  try {
+    parse(raw, inferred);
+    error.value = "";
+  } catch (err) {
+    error.value = (err as Error).message;
+  }
+  input.value = "";
+}
+</script>
+
+<template>
+  <div ref="rootRef" class="param-editor">
+    <div class="param-editor-toolbar">
+      <SelectBox
+        :model-value="format"
+        aria-label="Format"
+        :options="formatOptions"
+        @update:model-value="(v: string | undefined) => v && onFormatChange(v)"
+      />
+      <div class="param-editor-actions">
+        <Button variant="secondary" @click="handleImport">Import</Button>
+        <Button variant="secondary" @click="handleExport">Export</Button>
+        <Button @click="handleApply">Apply</Button>
+      </div>
+      <input
+        ref="fileInput"
+        type="file"
+        accept=".json,.toml,.yaml,.yml,application/json,text/plain"
+        class="param-editor-file-input"
+        tabindex="-1"
+        aria-hidden="true"
+        @change="onFileChange"
+      />
+    </div>
+    <Codemirror
+      v-model="text"
+      :extensions="extensions"
+      :style="{ height }"
+      :indent-with-tab="false"
+      :tab-size="2"
+      class="param-editor-cm"
+      @blur="handleBlur"
+    />
+    <div class="param-editor-error-region" role="status">
+      <Box v-if="error" variant="error" class="param-editor-error">
+        {{ error }}
+      </Box>
+    </div>
+    <p class="param-editor-shortcut-hint">
+      Press <kbd>{{ applyShortcut }}</kbd> to apply, or click outside the
+      editor.
+    </p>
+  </div>
+</template>
+
+<style scoped>
+.param-editor {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5em;
+  min-width: 0;
+}
+
+.param-editor-toolbar {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5em;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.param-editor-actions {
+  display: flex;
+  gap: 0.25em;
+}
+
+.param-editor-file-input {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  border: 0;
+}
+
+.param-editor-cm {
+  border: 1px solid var(--color-border);
+  border-radius: 0.375em;
+  font-size: var(--font-size-sm);
+  overflow: hidden;
+}
+
+.param-editor-cm :deep(.cm-editor) {
+  height: 100%;
+  outline: none;
+}
+
+.param-editor-cm :deep(.cm-editor.cm-focused) {
+  outline: none;
+}
+
+.param-editor-cm :deep(.cm-scroller) {
+  font-family:
+    ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono",
+    "Courier New", monospace;
+}
+
+.param-editor-error {
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.param-editor-shortcut-hint {
+  margin: 0;
+  font-size: var(--font-size-xs, 0.75em);
+  color: var(--color-text-secondary, #666);
+}
+
+.param-editor-shortcut-hint kbd {
+  font-family: inherit;
+  padding: 0.1em 0.35em;
+  border: 1px solid var(--color-border);
+  border-radius: 0.25em;
+  background: var(--color-bg-1, transparent);
+  font-size: 0.95em;
+}
+</style>

package/components/SidebarLayout/SidebarLayout.vue

@@ -13,9 +13,11 @@ import LightDarkToggle from "../LightDarkToggle/LightDarkToggle.vue";
 
 // Optional vue-router integration (no hard dependency).
 // $router/$route on globalProperties is vue-router's stable public API.
+// $route is defined as a getter that returns the current route, so we
+// must re-read it from globalProperties on each access to track changes.
 const instance = getCurrentInstance();
-const router = instance?.appContext.config.globalProperties.$router;
-const route = instance?.appContext.config.globalProperties.$route;
+const globals = instance?.appContext.config.globalProperties;
+const router = globals?.$router;
 
 export interface Tab {
   value: string;
@@ -68,14 +70,13 @@ const activeTab = computed({
 });
 
 // Sync active tab from route changes in router mode
-if (route) {
+if (globals) {
   watch(
-    () => route.path,
-    () => {
-      if (isRouterMode.value) {
-        const match = props.tabs?.find((t) => t.to === route.path);
-        if (match) tab.value = match.value;
-      }
+    () => globals.$route?.path,
+    (path) => {
+      if (!path || !isRouterMode.value) return;
+      const match = props.tabs?.find((t) => t.to === path);
+      if (match) tab.value = match.value;
     },
     { immediate: true },
   );

package/components/index.ts

@@ -11,6 +11,11 @@ export { default as Icon } from "./Icon/Icon.vue";
 export { default as LightDarkToggle } from "./LightDarkToggle/LightDarkToggle.vue";
 export { default as NumberInput } from "./NumberInput/NumberInput.vue";
 export type { NumberRange } from "./NumberInput/NumberInput.vue";
+export { default as ParamEditor } from "./ParamEditor/ParamEditor.vue";
+export type {
+  ParamEditorFormat,
+  ParamEditorValue,
+} from "./ParamEditor/ParamEditor.vue";
 export { default as SelectBox } from "./SelectBox/SelectBox.vue";
 export type { SelectOption } from "./SelectBox/SelectBox.vue";
 export { default as SidebarLayout } from "./SidebarLayout/SidebarLayout.vue";

package/index.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.5",
+  "version": "0.4.6",
   "package": "@cfasim-ui/docs",
   "content": {
     "components": [
@@ -83,6 +83,23 @@
         "source": "components/NumberInput/NumberInput.vue",
         "keywords": []
       },
+      {
+        "name": "ParamEditor",
+        "slug": "param-editor",
+        "docs": "components/ParamEditor/ParamEditor.md",
+        "source": "components/ParamEditor/ParamEditor.vue",
+        "keywords": [
+          "parameters",
+          "editor",
+          "code",
+          "json",
+          "toml",
+          "yaml",
+          "codemirror",
+          "import",
+          "export"
+        ]
+      },
       {
         "name": "SelectBox",
         "slug": "select-box",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfasim-ui/docs",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "LLM-friendly component and chart documentation for cfasim-ui",
   "license": "Apache-2.0",
   "repository": {

package/wasm/index.ts

@@ -1,2 +1,2 @@
-export { runWasm } from "./wasmWorkerApi.js";
+export { runWasm, cancelWasm } from "./wasmWorkerApi.js";
 export { useModel } from "./useModel.js";