@malloy-publisher/sdk 0.0.199 → 0.0.201

package/src/components/Notebook/Notebook.tsx

@@ -11,7 +11,10 @@ import {
    FilterSelection,
    useDimensionFilters,
 } from "../../hooks/useDimensionFilters";
+import { GivenValue, useGivensForm } from "../../hooks/useGivensForm";
+import { useModelGivens } from "../../hooks/useModelGivens";
 import { useQueryWithApiError } from "../../hooks/useQueryWithApiError";
+import { parseResourceUri } from "../../utils/formatting";
 import { ApiErrorDisplay } from "../ApiErrorDisplay";
 import { DimensionFilter, RetrievalFunction } from "../filter/DimensionFilter";
 import {
@@ -19,8 +22,7 @@ import {
    parseAllSourceInfos,
    parseNotebookFilterAnnotation,
 } from "../filter/utils";
-
-import { parseResourceUri } from "../../utils/formatting";
+import { GivensPanel } from "../given";
 import { Loading } from "../Loading";
 import { useServer } from "../ServerProvider";
 import { CleanNotebookContainer, CleanNotebookSection } from "../styles";
@@ -216,6 +218,14 @@ export default function Notebook({
       [filterStates, getActiveFilters],
    );
 
+   // Extract model-level givens declared via `given:` and manage user overrides
+   const declaredGivens = useModelGivens(notebook);
+   const {
+      givenValues,
+      updateGiven,
+      clearAll: clearAllGivens,
+   } = useGivensForm(declaredGivens);
+
    // Create a map of dimension key -> source name for quick lookup (used by filter UI)
    const _dimensionToSourceMap = useMemo(() => {
       const map = new Map<string, string>();
@@ -273,11 +283,40 @@ export default function Notebook({
       [],
    );
 
+   /**
+    * Serialize given-value overrides into the JSON-encoded string the server
+    * expects on the notebook-cell GET endpoint's `givens` query param.
+    * Date values are rendered as YYYY-MM-DD; everything else passes through
+    * the standard JSON encoder.
+    */
+   const buildGivens = useCallback(
+      (values: Map<string, GivenValue>): string | undefined => {
+         if (values.size === 0) return undefined;
+         const encode = (v: GivenValue): unknown => {
+            if (v instanceof Date) return v.toISOString().slice(0, 10);
+            if (Array.isArray(v)) return v.map((item) => encode(item));
+            return v;
+         };
+         const params: Record<string, unknown> = {};
+         values.forEach((value, name) => {
+            if (value === null || value === undefined) return;
+            params[name] = encode(value);
+         });
+         return Object.keys(params).length > 0
+            ? JSON.stringify(params)
+            : undefined;
+      },
+      [],
+   );
+
    // Unified cell execution function
-   // Executes all notebook cells, passing server-side filter params when available
+   // Executes all notebook cells, passing server-side filter params and givens
    // Runs up to 4 requests in parallel for better performance
    const executeCells = useCallback(
-      async (filtersToApply: FilterSelection[] = []) => {
+      async (
+         filtersToApply: FilterSelection[] = [],
+         givensToApply: Map<string, GivenValue> = new Map(),
+      ) => {
          if (!isSuccess || !notebook?.notebookCells) return;
 
          // Initialize or reset cells
@@ -297,6 +336,7 @@ export default function Notebook({
          const filterParams = useServerFilters
             ? buildFilterParams(filtersToApply)
             : undefined;
+         const givensParam = buildGivens(givensToApply);
 
          try {
             // Build execution tasks for code cells
@@ -313,7 +353,7 @@ export default function Notebook({
 
                const executeCell = async () => {
                   try {
-                     // Use notebook cell execution API with optional filter_params
+                     // Use notebook cell execution API with optional filter_params and givens
                      const response =
                         await apiClients.notebooks.executeNotebookCell(
                            environmentName,
@@ -322,6 +362,8 @@ export default function Notebook({
                            cellIndex,
                            versionId,
                            filterParams,
+                           undefined,
+                           givensParam,
                         );
 
                      const executedCell = response.data;
@@ -381,6 +423,7 @@ export default function Notebook({
          notebook,
          useServerFilters,
          buildFilterParams,
+         buildGivens,
          environmentName,
          packageName,
          notebookPath,
@@ -389,45 +432,52 @@ export default function Notebook({
       ],
    );
 
-   // Execute cells when notebook is loaded (no filters initially)
+   // Execute cells when notebook is loaded (no filters or givens initially)
    useEffect(() => {
       if (!isSuccess || !notebook?.notebookCells) return;
-      executeCells([]);
+      executeCells([], new Map());
    }, [isSuccess, notebook, executeCells]);
 
-   // Re-execute when filters change
-   // Track previous activeFilters to detect actual changes (not just reference changes)
-   const prevActiveFiltersRef = useRef<string>("");
+   // Re-execute when filters or givens change
+   // Track previous input shape to detect actual value changes (not just reference changes)
+   const prevInputsRef = useRef<string>("");
 
    useEffect(() => {
-      // Serialize activeFilters to detect actual value changes
-      const serialized = JSON.stringify(
-         activeFilters.map((f) => ({
+      // Serialize activeFilters + givenValues to detect actual value changes
+      const serialized = JSON.stringify({
+         filters: activeFilters.map((f) => ({
             dim: f.dimensionName,
             type: f.matchType,
             val: f.value,
             val2: f.value2,
          })),
-      );
+         givens: Array.from(givenValues.entries()).sort(([a], [b]) =>
+            a.localeCompare(b),
+         ),
+      });
 
-      // Skip if no actual change or if this is the initial empty state
-      if (serialized === prevActiveFiltersRef.current) {
+      // Skip if no actual change
+      if (serialized === prevInputsRef.current) {
          return;
       }
 
-      // Skip the initial render (when prevActiveFiltersRef is empty and filters are also empty)
-      if (prevActiveFiltersRef.current === "" && activeFilters.length === 0) {
-         prevActiveFiltersRef.current = serialized;
+      // Skip the initial render when both inputs are empty
+      if (
+         prevInputsRef.current === "" &&
+         activeFilters.length === 0 &&
+         givenValues.size === 0
+      ) {
+         prevInputsRef.current = serialized;
          return;
       }
 
-      prevActiveFiltersRef.current = serialized;
+      prevInputsRef.current = serialized;
 
-      // Re-execute with current filters (or no filters if cleared)
+      // Re-execute with current filters and givens (or empty if cleared)
       if (!isExecuting) {
-         executeCells(activeFilters);
+         executeCells(activeFilters, givenValues);
       }
-   }, [activeFilters, isExecuting, executeCells]);
+   }, [activeFilters, givenValues, isExecuting, executeCells]);
 
    // Handle filter change using composite key
    const handleFilterChange = useCallback(
@@ -447,6 +497,14 @@ export default function Notebook({
       <CleanNotebookContainer>
          <CleanNotebookSection>
             <Stack spacing={3} component="section">
+               {/* Givens Panel — runtime parameters declared via `given:` */}
+               <GivensPanel
+                  givens={declaredGivens}
+                  values={givenValues}
+                  onChange={updateGiven}
+                  onClearAll={clearAllGivens}
+               />
+
                {/* Filter Panel */}
                {dimensionSpecs.length > 0 && filterValuesData && (
                   <Paper

package/src/components/Package/Package.tsx

@@ -27,9 +27,6 @@ import { useServer } from "../ServerProvider";
 import { encodeResourceUri, parseResourceUri } from "../../utils/formatting";
 import { MALLOY_BRAND, MONO_FONT_FAMILY } from "../styles";
 import ContentTypeIcon from "./ContentTypeIcon";
-// TODO(redesign-followup): port the Connections section into the redesigned
-// flat-row aesthetic (currently rendered with its original card/table styling).
-import Connections from "./Connections";
 
 const README_NOTEBOOK = "README.malloynb";
 
@@ -213,10 +210,6 @@ export default function Package({
                   {databases.length === 0 && <EmptyRow label="No data files" />}
                </PackageSection>
 
-               <Box sx={{ mb: 4 }}>
-                  <Connections resourceUri={resourceUri} />
-               </Box>
-
                {hasReadme && (
                   <Box sx={{ mt: 6 }}>
                      <Notebook

package/src/components/given/GivenInput.tsx

@@ -0,0 +1,190 @@
+import ClearIcon from "@mui/icons-material/Clear";
+import {
+   Autocomplete,
+   Checkbox,
+   FormControlLabel,
+   IconButton,
+   InputAdornment,
+   TextField,
+} from "@mui/material";
+import { AdapterDayjs } from "@mui/x-date-pickers/AdapterDayjs";
+import { DatePicker } from "@mui/x-date-pickers/DatePicker";
+import { LocalizationProvider } from "@mui/x-date-pickers/LocalizationProvider";
+import dayjs from "dayjs";
+import utc from "dayjs/plugin/utc";
+import { Given } from "../../client";
+import { GivenValue } from "../../hooks/useGivensForm";
+
+dayjs.extend(utc);
+
+export interface GivenInputProps {
+   given: Given;
+   value: GivenValue | undefined;
+   onChange: (next: GivenValue) => void;
+}
+
+/**
+ * Distill a given's `#(...)` annotation list into helper text for the UI.
+ * If an annotation includes `description="..."` (a Malloy convention), the
+ * quoted value is surfaced verbatim. Otherwise the annotation contents
+ * inside `#(...)` are joined as-is so model authors still see something
+ * recognizable. Returns undefined when nothing is renderable.
+ */
+function annotationHelperText(given: Given): string | undefined {
+   const visible = (given.annotations ?? []).filter((a) =>
+      a.trim().startsWith("#("),
+   );
+   if (visible.length === 0) return undefined;
+
+   const rendered: string[] = [];
+   for (const raw of visible) {
+      const trimmed = raw.trim();
+      const descriptionMatch = trimmed.match(/description="([^"]*)"/);
+      if (descriptionMatch) {
+         rendered.push(descriptionMatch[1]);
+         continue;
+      }
+      // Strip leading `#(` and trailing `)`, then push the inner content
+      const inner = trimmed
+         .replace(/^#\(/, "")
+         .replace(/\)\s*$/, "")
+         .trim();
+      if (inner) rendered.push(inner);
+   }
+   return rendered.length > 0 ? rendered.join("\n") : undefined;
+}
+
+/**
+ * Renders an input widget appropriate for the declared given type.
+ * Unknown / unrecognized types fall back to a plain text input.
+ *
+ * For text-based inputs (string, number, filter, default), a clear (×)
+ * adornment appears when the field has a value. DatePicker, Checkbox, and
+ * multi-Autocomplete have their own native clear affordances.
+ */
+export function GivenInput({ given, value, onChange }: GivenInputProps) {
+   const label = given.name ?? "";
+   const type = given.type ?? "string";
+   const helperText = annotationHelperText(given);
+
+   if (type === "boolean") {
+      const checked = value === true;
+      // Checkbox wrapped in FormControlLabel — no helperText slot available.
+      return (
+         <FormControlLabel
+            control={
+               <Checkbox
+                  checked={checked}
+                  onChange={(e) => onChange(e.target.checked)}
+               />
+            }
+            label={label}
+         />
+      );
+   }
+
+   if (type === "number") {
+      const num = typeof value === "number" ? value : "";
+      return (
+         <TextField
+            label={label}
+            type="number"
+            value={num}
+            onChange={(e) => {
+               const v = e.target.value;
+               onChange(v === "" ? null : Number(v));
+            }}
+            helperText={helperText}
+            slotProps={{
+               input: {
+                  endAdornment: num !== "" && (
+                     <ClearAdornment onClear={() => onChange(null)} />
+                  ),
+               },
+            }}
+            fullWidth
+            size="small"
+         />
+      );
+   }
+
+   if (type === "date" || type === "timestamp" || type === "timestamptz") {
+      const dateValue = value instanceof Date ? dayjs.utc(value) : null;
+      return (
+         <LocalizationProvider dateAdapter={AdapterDayjs}>
+            <DatePicker
+               label={label}
+               value={dateValue}
+               onChange={(next) => onChange(next ? next.toDate() : null)}
+               slotProps={{
+                  textField: { fullWidth: true, size: "small", helperText },
+                  field: { clearable: true, onClear: () => onChange(null) },
+               }}
+            />
+         </LocalizationProvider>
+      );
+   }
+
+   if (type.startsWith("array<")) {
+      const list = Array.isArray(value) ? value.map(String) : [];
+      return (
+         <Autocomplete
+            multiple
+            freeSolo
+            options={[]}
+            value={list}
+            onChange={(_event, next) =>
+               onChange(next.length === 0 ? null : (next as string[]))
+            }
+            renderInput={(params) => (
+               <TextField
+                  {...params}
+                  label={label}
+                  size="small"
+                  helperText={helperText}
+               />
+            )}
+            fullWidth
+         />
+      );
+   }
+
+   // Default: string, filter<...>, or unknown types — plain text input
+   const str = typeof value === "string" ? value : "";
+   return (
+      <TextField
+         label={label}
+         value={str}
+         onChange={(e) => {
+            const v = e.target.value;
+            onChange(v === "" ? null : v);
+         }}
+         placeholder={type.startsWith("filter<") ? type : undefined}
+         helperText={helperText}
+         slotProps={{
+            input: {
+               endAdornment: str !== "" && (
+                  <ClearAdornment onClear={() => onChange(null)} />
+               ),
+            },
+         }}
+         fullWidth
+         size="small"
+      />
+   );
+}
+
+function ClearAdornment({ onClear }: { onClear: () => void }) {
+   return (
+      <InputAdornment position="end">
+         <IconButton
+            size="small"
+            aria-label="clear value"
+            onClick={onClear}
+            edge="end"
+         >
+            <ClearIcon fontSize="small" />
+         </IconButton>
+      </InputAdornment>
+   );
+}

package/src/components/given/GivensPanel.tsx

@@ -0,0 +1,85 @@
+import { Box, Button, Paper, Stack, Typography } from "@mui/material";
+import { Given } from "../../client";
+import { GivenValue } from "../../hooks/useGivensForm";
+import { GivenInput } from "./GivenInput";
+
+export interface GivensPanelProps {
+   givens: Given[];
+   values: Map<string, GivenValue>;
+   onChange: (name: string, value: GivenValue) => void;
+   onClearAll: () => void;
+}
+
+/**
+ * Renders the "Parameters" panel — one input per declared `given:`.
+ * Returns null when the model declares no givens, so callers can drop
+ * `<GivensPanel ... />` unconditionally without a length guard.
+ *
+ * A "Reset" button appears in the panel header when at least one value
+ * is set; it fires `onClearAll` which the parent should wire to
+ * `useGivensForm.clearAll`.
+ */
+export function GivensPanel({
+   givens,
+   values,
+   onChange,
+   onClearAll,
+}: GivensPanelProps) {
+   if (givens.length === 0) return null;
+   const hasValues = values.size > 0;
+
+   return (
+      <Paper
+         elevation={0}
+         sx={{
+            p: 3,
+            backgroundColor: "transparent",
+            border: "none",
+            boxShadow: "none",
+         }}
+      >
+         <Stack
+            direction="row"
+            alignItems="center"
+            justifyContent="space-between"
+            sx={{ mb: 2 }}
+         >
+            <Typography
+               variant="subtitle2"
+               sx={{ fontWeight: 600, color: "#333" }}
+            >
+               Parameters
+            </Typography>
+            {hasValues && (
+               <Button
+                  variant="text"
+                  size="small"
+                  onClick={onClearAll}
+                  sx={{ textTransform: "none" }}
+               >
+                  Reset
+               </Button>
+            )}
+         </Stack>
+         <Box
+            sx={{
+               display: "grid",
+               gridTemplateColumns: "repeat(auto-fill, minmax(250px, 1fr))",
+               gap: 3,
+            }}
+         >
+            {givens.map((given) => (
+               <Box key={given.name}>
+                  <GivenInput
+                     given={given}
+                     value={given.name ? values.get(given.name) : undefined}
+                     onChange={(next) =>
+                        given.name && onChange(given.name, next)
+                     }
+                  />
+               </Box>
+            ))}
+         </Box>
+      </Paper>
+   );
+}

package/src/components/given/index.ts

@@ -0,0 +1,2 @@
+export { GivenInput, type GivenInputProps } from "./GivenInput";
+export { GivensPanel, type GivensPanelProps } from "./GivensPanel";

package/src/hooks/index.ts

@@ -31,3 +31,11 @@ export {
    type FilterType,
    type UseDimensionalFilterRangeDataParams,
 } from "./useDimensionalFilterRangeData";
+
+// Givens hooks and types
+export { useModelGivens } from "./useModelGivens";
+export {
+   useGivensForm,
+   type GivenValue,
+   type UseGivensFormResult,
+} from "./useGivensForm";

package/src/hooks/useGivensForm.ts

@@ -0,0 +1,110 @@
+import { useCallback, useEffect, useState } from "react";
+import { Given } from "../client";
+
+/**
+ * UI-side value for a given. Mirrors the JS shapes the server accepts
+ * for `givens` runtime values, plus `Date` (serialized to ISO before send).
+ */
+export type GivenValue =
+   | string
+   | number
+   | boolean
+   | Date
+   | string[]
+   | number[]
+   | null;
+
+/**
+ * Result from the useGivensForm hook
+ */
+export interface UseGivensFormResult {
+   /** Current value for each given, keyed by given name. Missing keys mean "use the model default". */
+   givenValues: Map<string, GivenValue>;
+   /** Update a given's value. Pass `null` to revert to model default. */
+   updateGiven: (name: string, value: GivenValue) => void;
+   /** Remove a single given override. */
+   clearGiven: (name: string) => void;
+   /** Remove all overrides. */
+   clearAll: () => void;
+   /** Map of just the givens that have a user-supplied (non-null) override. */
+   getActiveGivens: () => Map<string, Exclude<GivenValue, null>>;
+}
+
+/**
+ * Manages user-supplied values for model `given:` parameters.
+ *
+ * Mirrors the shape of [`useDimensionFilters`](./useDimensionFilters.ts):
+ * one entry per declared given, keyed by name (no source qualifier — givens
+ * are model-level, not per-source).
+ *
+ * When `givens` (the introspected list) changes (e.g., after the notebook
+ * loads), existing user overrides are preserved for matching names and new
+ * givens are added as empty.
+ */
+export function useGivensForm(givens: Given[]): UseGivensFormResult {
+   const [givenValues, setGivenValues] = useState<Map<string, GivenValue>>(
+      () => new Map(),
+   );
+
+   // Sync the form when the declared givens list changes (e.g., model reloaded).
+   // Preserve existing values for givens that still exist; drop values for givens
+   // that no longer exist.
+   useEffect(() => {
+      setGivenValues((prev) => {
+         const declared = new Set(
+            givens.map((g) => g.name).filter((n): n is string => !!n),
+         );
+         const next = new Map<string, GivenValue>();
+         prev.forEach((value, name) => {
+            if (declared.has(name)) next.set(name, value);
+         });
+         return next;
+      });
+   }, [givens]);
+
+   const updateGiven = useCallback((name: string, value: GivenValue) => {
+      setGivenValues((prev) => {
+         const next = new Map(prev);
+         if (value === null) {
+            next.delete(name);
+         } else {
+            next.set(name, value);
+         }
+         return next;
+      });
+   }, []);
+
+   const clearGiven = useCallback((name: string) => {
+      setGivenValues((prev) => {
+         if (!prev.has(name)) return prev;
+         const next = new Map(prev);
+         next.delete(name);
+         return next;
+      });
+   }, []);
+
+   const clearAll = useCallback(() => {
+      setGivenValues((prev) => (prev.size === 0 ? prev : new Map()));
+   }, []);
+
+   const getActiveGivens = useCallback((): Map<
+      string,
+      Exclude<GivenValue, null>
+   > => {
+      const active = new Map<string, Exclude<GivenValue, null>>();
+      givenValues.forEach((value, name) => {
+         if (value !== null && value !== undefined) {
+            active.set(name, value);
+         }
+      });
+      return active;
+   }, [givenValues]);
+
+   return {
+      givenValues,
+      updateGiven,
+      clearGiven,
+      clearAll,
+      getActiveGivens,
+   };
+}

package/src/hooks/useModelGivens.ts

@@ -0,0 +1,26 @@
+import { useMemo } from "react";
+import { Given, RawNotebook } from "../client";
+
+/**
+ * Extracts the deduplicated list of model-level `given:` declarations from
+ * a notebook's sources. The server attaches the same model-level givens to
+ * every `Source` for SDK ergonomics (see #761); this hook collapses them
+ * back to one entry per name so callers render a single input per given.
+ *
+ * Returns an empty array when no givens are declared on any source.
+ */
+export function useModelGivens(notebook: RawNotebook | undefined): Given[] {
+   return useMemo(() => {
+      if (!notebook?.sources?.length) return [];
+      const byName = new Map<string, Given>();
+      for (const source of notebook.sources) {
+         if (!source.givens?.length) continue;
+         for (const given of source.givens) {
+            if (given.name && !byName.has(given.name)) {
+               byName.set(given.name, given);
+            }
+         }
+      }
+      return Array.from(byName.values());
+   }, [notebook]);
+}