Surface time dimensions in time pickers (#9608)

* feat: surface time dimensions in time pickers

- Visual metrics editor: time picker now lists defined time dimensions
  (with display name and description) alongside raw timestamp columns,
  grouped under section headers.
- Explore/Canvas time picker: primary range tooltip shows the active
  time dimension's name and description when the time axis is a
  dimension (not a raw column).
- Hide the time axis switcher when there is only one time dimension.

* Show display name (not raw column) in time axis trigger

Only render the time axis name when it resolves to a defined time
dimension, using its display name; hide it for a raw column.

Author: nishantmonu51

web-common/src/components/forms/Input.svelte

@@ -47,7 +47,15 @@
   export let leadingIcon: ComponentType<SvelteComponent> | undefined =
     undefined;
   export let options:
-    | { value: string; label: string; type?: string }[]
+    | {
+        value: string;
+        label: string;
+        type?: string;
+        description?: string;
+        tooltip?: string;
+        icon?: ComponentType<SvelteComponent>;
+        group?: string;
+      }[]
     | undefined = undefined;
   export let additionalClass = "";
   export let onInput: (

web-common/src/components/forms/Select.svelte

@@ -23,6 +23,9 @@
     disabled?: boolean;
     tooltip?: string;
     icon?: ComponentType<SvelteComponent>;
+    /** Optional section heading; a heading is rendered above the first
+     * option of each consecutive group. */
+    group?: string;
   }[];
   export let optionsLoading: boolean = false;
   export let onAddNew: (() => void) | null = null;
@@ -182,7 +185,14 @@
             </div>
           </div>
         {:else}
-          {#each filteredOptions as { type, value, label, description, disabled, tooltip, icon } (value)}
+          {#each filteredOptions as { type, value, label, description, disabled, tooltip, icon, group }, i (value)}
+            {#if group && group !== filteredOptions[i - 1]?.group}
+              <div
+                class="px-2 pt-2 pb-1 text-fg-secondary text-[11px] font-semibold uppercase tracking-wide"
+              >
+                {group}
+              </div>
+            {/if}
             <Select.Item
               {value}
               {label}
@@ -192,7 +202,9 @@
             >
               {#if tooltip}
                 <Tooltip.Root>
-                  <Tooltip.Trigger class="select-tooltip cursor-default">
+                  <Tooltip.Trigger
+                    class="inline-flex items-center gap-x-2 cursor-default text-left"
+                  >
                     {#if icon}
                       <svelte:component this={icon} size="16px" />
                     {:else if type}

web-common/src/features/dashboards/filters/Filters.svelte

@@ -200,7 +200,8 @@
   $: timeDimensionOptions = $timeDimensions.map((timeDim) => {
     return {
       value: timeDim.name!,
-      label: timeDim.name!,
+      label: timeDim.displayName || timeDim.name!,
+      description: timeDim.description,
     };
   });
 

web-common/src/features/dashboards/time-controls/super-pill/SuperPill.svelte

@@ -45,7 +45,11 @@
   export let side: "top" | "right" | "bottom" | "left" = "bottom";
   export let primaryTimeDimension: string | undefined = undefined;
   export let selectedTimeDimension: string | undefined = undefined;
-  export let timeDimensions: { value: string; label: string }[] = [];
+  export let timeDimensions: {
+    value: string;
+    label: string;
+    description?: string;
+  }[] = [];
   export let onSelectRange: (range: NamedRange | ISODurationString) => void;
   export let onPan: (direction: "left" | "right") => void;
   export let onTimeGrainSelect: (timeGrain: V1TimeGrain) => void;

web-common/src/features/dashboards/time-controls/super-pill/new-time-dropdown/PrimaryRangeTooltip.svelte

@@ -4,9 +4,22 @@
 
   export let timeString: string | undefined;
   export let interval: Interval<true>;
+  // Set only when the active time axis is a time dimension (not a raw column).
+  export let timeDimensionLabel: string | undefined = undefined;
+  export let timeDimensionDescription: string | undefined = undefined;
 </script>
 
 <TooltipContent class="flex-col flex items-center gap-y-0 p-3">
+  {#if timeDimensionLabel}
+    <div class="flex flex-col items-center mb-1">
+      <span class="font-bold text-fg-inverse">{timeDimensionLabel}</span>
+      {#if timeDimensionDescription}
+        <span class="text-fg-inverse/70 text-center max-w-64">
+          {timeDimensionDescription}
+        </span>
+      {/if}
+    </div>
+  {/if}
   <span class="font-semibold italic mb-1">{timeString}</span>
   {#if interval.isValid}
     <span

web-common/src/features/dashboards/time-controls/super-pill/new-time-dropdown/RangePickerV2.svelte

@@ -62,7 +62,11 @@
   export let availableTimeZones: string[];
   export let lockTimeZone = false;
   export let showFullRange = true;
-  export let timeDimensions: { value: string; label: string }[];
+  export let timeDimensions: {
+    value: string;
+    label: string;
+    description?: string;
+  }[];
   export let primaryTimeDimension: string | undefined;
   export let selectedTimeDimension: string | undefined;
   export let onTimeDimensionSelect: ((dimension: string) => void) | undefined =
@@ -109,6 +113,13 @@
 
   $: selectedLabel = getRangeLabel(timeString);
 
+  // Resolve the active time axis to a defined time dimension, if any. When the
+  // timeseries points at a raw column this is undefined and the tooltip omits
+  // the dimension name and description.
+  $: activeTimeDimension = timeDimensions.find(
+    ({ value }) => value === (selectedTimeDimension || primaryTimeDimension),
+  );
+
   $: zoneAbbreviation = getAbbreviationForIANA(maxDate ?? DateTime.now(), zone);
 
   $: smallestTimeGrainOrder = getGrainOrder(
@@ -269,7 +280,12 @@
 
     <Tooltip.Content side="bottom" sideOffset={8} class="z-50">
       {#if interval}
-        <PrimaryRangeTooltip {timeString} {interval} />
+        <PrimaryRangeTooltip
+          {timeString}
+          {interval}
+          timeDimensionLabel={activeTimeDimension?.label}
+          timeDimensionDescription={activeTimeDimension?.description}
+        />
       {/if}
     </Tooltip.Content>
   </Tooltip.Root>
@@ -429,7 +445,7 @@
           </div>
         {/if}
 
-        {#if timeDimensions.length && onTimeDimensionSelect}
+        {#if timeDimensions.length > 1 && onTimeDimensionSelect}
           <div class="w-full h-fit px-1">
             <div class="h-px w-full bg-gray-200 my-1"></div>
 
@@ -446,11 +462,11 @@
                   <Clock size="14px" />
                 </div>
                 <div class="mr-auto">Time axis</div>
-                <div class="sr-only group-hover:not-sr-only">
-                  <SyntaxElement
-                    range={selectedTimeDimension || primaryTimeDimension}
-                  />
-                </div>
+                {#if activeTimeDimension}
+                  <div class="sr-only group-hover:not-sr-only">
+                    <SyntaxElement range={activeTimeDimension.label} />
+                  </div>
+                {/if}
                 <CaretDownIcon className="-rotate-90" size="14px" />
               </Popover.Trigger>
 
@@ -460,21 +476,41 @@
                 sideOffset={12}
                 class="p-1 z-50"
               >
-                {#each timeDimensions as { value, label } (value)}
-                  <button
-                    class="item"
-                    aria-label="Select {label} time dimension"
-                    onclick={() => {
-                      onTimeDimensionSelect(value);
-                      closeMenu();
-                      timeAxisPickerOpen = false;
-                    }}
-                  >
-                    {label}
-                    {#if value === (selectedTimeDimension || primaryTimeDimension)}
-                      <Check class="size-4" color="var(--color-gray-800)" />
+                {#each timeDimensions as { value, label, description } (value)}
+                  <Tooltip.Root>
+                    <Tooltip.Trigger>
+                      {#snippet child({ props })}
+                        <button
+                          {...props}
+                          class="item"
+                          aria-label="Select {label} time dimension"
+                          onclick={() => {
+                            onTimeDimensionSelect(value);
+                            closeMenu();
+                            timeAxisPickerOpen = false;
+                          }}
+                        >
+                          {label}
+                          {#if value === (selectedTimeDimension || primaryTimeDimension)}
+                            <Check
+                              class="size-4"
+                              color="var(--color-gray-800)"
+                            />
+                          {/if}
+                        </button>
+                      {/snippet}
+                    </Tooltip.Trigger>
+                    {#if description}
+                      <Tooltip.Content
+                        side="right"
+                        sideOffset={8}
+                        class="max-w-64"
+                      >
+                        <div class="font-bold text-fg-inverse">{label}</div>
+                        <div class="text-fg-inverse/70">{description}</div>
+                      </Tooltip.Content>
                     {/if}
-                  </button>
+                  </Tooltip.Root>
                 {/each}
               </Popover.Content>
             </Popover.Root>

web-common/src/features/workspaces/VisualMetrics.svelte

@@ -23,7 +23,7 @@
     type V1Resource,
   } from "@rilldata/web-common/runtime-client/gen/index.schemas";
   import { useRuntimeClient } from "@rilldata/web-common/runtime-client/v2";
-  import { PlusIcon } from "lucide-svelte";
+  import { Clock, PlusIcon } from "lucide-svelte";
   import { tick } from "svelte";
   import { parseDocument, Scalar, YAMLMap, YAMLSeq } from "yaml";
   import ConnectorExplorer from "../connectors/explorer/ConnectorExplorer.svelte";
@@ -216,9 +216,7 @@
 
   $: columns = columnsResponse?.profileColumns ?? [];
 
-  $: timeOptions = columns
-    .filter(({ type }) => type && TIMESTAMPS.has(type))
-    .map(({ name }) => ({ value: name ?? "", label: name ?? "" }));
+  $: timeColumns = columns.filter(({ type }) => type && TIMESTAMPS.has(type));
 
   $: typeOfSelectedTimeDimension = columns.find(
     ({ name }) => name === timeDimension,
@@ -249,6 +247,39 @@
         : [],
   };
 
+  // Time dimensions defined in the metrics view can be selected as the primary
+  // time dimension in addition to raw timestamp columns.
+  $: timeDimensionOptions = itemGroups.dimensions
+    .filter((d) => d.type === "time")
+    .map((d) => {
+      const value = d.name || d.resourceName;
+      return {
+        value,
+        label: d.display_name || value,
+        tooltip: d.description || undefined,
+        icon: Clock,
+        group: "Time dimensions",
+      };
+    })
+    .filter(({ value }) => value);
+
+  $: timeDimensionValues = new Set(
+    timeDimensionOptions.map(({ value }) => value),
+  );
+
+  $: timeOptions = [
+    ...timeDimensionOptions,
+    ...timeColumns
+      .filter(({ name }) => !timeDimensionValues.has(name ?? ""))
+      .map(({ name, type }) => ({
+        value: name ?? "",
+        label: name ?? "",
+        type,
+        // Only label the columns section when time dimensions are also listed.
+        group: timeDimensionOptions.length ? "Columns" : undefined,
+      })),
+  ];
+
   $: dimensionNamesAndLabels = itemGroups.dimensions.reduce(
     (acc, { name, display_name, resourceName }) => {
       acc.name = Math.max(acc.name, name.length || resourceName?.length || 0);
@@ -685,7 +716,7 @@
         disabledMessage={!hasValidModelOrSourceSelection
           ? "No model selected"
           : "No timestamp columns in model"}
-        hint="Column from model that will be used as primary time dimension in dashboards"
+        hint="Time dimension or timestamp column used as the primary time dimension in dashboards"
         onChange={async (value) => {
           await updateProperties({ timeseries: value });
         }}