Merge pull request #1948 from visualize-admin/docs/better-preview-via…

…-api-docs docs: Improve preview via API documentation
visualize-admin · Jan 8, 2025 · ef1ec7a · ef1ec7a
2 parents bc6676a + 217194a
commit ef1ec7a
Show file tree

Hide file tree

Showing 66 changed files with 40,479 additions and 476 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,8 +20,12 @@ You can also check the
   - Fixed preview via API (iframe)
   - Fixed cut table scroll-bars and unnecessary scroll of bar charts when
     switching between chart types
-  - Fixed map dimension symbols to increase the elements size for small values, whilst preventing any 0 and undefined values from displaying
+  - Fixed map dimension symbols to increase the elements size for small values,
+    whilst preventing any 0 and undefined values from displaying
   - Added Footer to the Profile Page
+- Docs
+  - Added auto-generated JSON Schema files for configurator state and chart
+    config and improved preview charts via API documentation
 
 # [5.0.2] - 2024-11-28
 

diff --git a/app/charts/bar/bars-grouped-state-props.ts b/app/charts/bar/bars-grouped-state-props.ts
@@ -22,8 +22,9 @@ import {
   useSegmentVariables,
 } from "@/charts/shared/chart-state";
 import { useRenderingKeyVariable } from "@/charts/shared/rendering-utils";
-import { BarConfig, useChartConfigFilters } from "@/configurator";
-import { Observation, isTemporalEntityDimension } from "@/domain/data";
+import { useChartConfigFilters } from "@/config-utils";
+import { BarConfig } from "@/configurator";
+import { isTemporalEntityDimension, Observation } from "@/domain/data";
 import { sortByIndex } from "@/utils/array";
 
 import { ChartProps } from "../shared/ChartProps";

diff --git a/app/charts/bar/bars-stacked-state-props.ts b/app/charts/bar/bars-stacked-state-props.ts
@@ -19,8 +19,9 @@ import {
   useSegmentVariables,
 } from "@/charts/shared/chart-state";
 import { useRenderingKeyVariable } from "@/charts/shared/rendering-utils";
-import { BarConfig, useChartConfigFilters } from "@/configurator";
-import { Observation, isTemporalEntityDimension } from "@/domain/data";
+import { useChartConfigFilters } from "@/config-utils";
+import { BarConfig } from "@/configurator";
+import { isTemporalEntityDimension, Observation } from "@/domain/data";
 import { sortByIndex } from "@/utils/array";
 
 import { ChartProps } from "../shared/ChartProps";

diff --git a/app/charts/bar/bars-state-props.ts b/app/charts/bar/bars-state-props.ts
@@ -19,7 +19,8 @@ import {
   useNumericalXVariables,
 } from "@/charts/shared/chart-state";
 import { useRenderingKeyVariable } from "@/charts/shared/rendering-utils";
-import { BarConfig, useChartConfigFilters } from "@/configurator";
+import { useChartConfigFilters } from "@/config-utils";
+import { BarConfig } from "@/configurator";
 import { isTemporalEntityDimension } from "@/domain/data";
 
 import { ChartProps } from "../shared/ChartProps";

diff --git a/app/charts/bar/chart-bar.tsx b/app/charts/bar/chart-bar.tsx
@@ -24,7 +24,8 @@ import {
 } from "@/charts/shared/containers";
 import { Tooltip } from "@/charts/shared/interaction/tooltip";
 import { LegendColor } from "@/charts/shared/legend-color";
-import { BarConfig, useChartConfigFilters } from "@/config-types";
+import { BarConfig } from "@/config-types";
+import { useChartConfigFilters } from "@/config-utils";
 import { hasChartConfigs } from "@/configurator";
 import { TimeSlider } from "@/configurator/interactive-filters/time-slider";
 import { useConfiguratorState } from "@/src";

diff --git a/app/charts/chart-config-ui-options.ts b/app/charts/chart-config-ui-options.ts
@@ -29,6 +29,8 @@ import {
   ComboLineSingleConfig,
   ComponentType,
   GenericField,
+  getAnimationField,
+  isSortingInConfig,
   LineConfig,
   MapConfig,
   PaletteType,
@@ -37,25 +39,23 @@ import {
   SortingOrder,
   SortingType,
   TableConfig,
-  getAnimationField,
-  isSortingInConfig,
-  makeMultiFilter,
 } from "@/config-types";
+import { makeMultiFilter } from "@/config-utils";
 import { getFieldLabel } from "@/configurator/components/field-i18n";
 import { mapValueIrisToColor } from "@/configurator/components/ui-helpers";
 import {
   ANIMATION_ENABLED_COMPONENTS,
   Component,
   Dimension,
-  MULTI_FILTER_ENABLED_COMPONENTS,
-  Measure,
-  Observation,
-  SEGMENT_ENABLED_COMPONENTS,
   isNumericalMeasure,
   isOrdinalMeasure,
   isTemporalDimension,
   isTemporalEntityDimension,
   isTemporalOrdinalDimension,
+  Measure,
+  MULTI_FILTER_ENABLED_COMPONENTS,
+  Observation,
+  SEGMENT_ENABLED_COMPONENTS,
 } from "@/domain/data";
 import { getDefaultCategoricalPaletteName, getPalette } from "@/palettes";
 

diff --git a/app/charts/column/chart-column.tsx b/app/charts/column/chart-column.tsx
@@ -24,7 +24,8 @@ import {
 } from "@/charts/shared/containers";
 import { Tooltip } from "@/charts/shared/interaction/tooltip";
 import { LegendColor } from "@/charts/shared/legend-color";
-import { ColumnConfig, useChartConfigFilters } from "@/config-types";
+import { ColumnConfig } from "@/config-types";
+import { useChartConfigFilters } from "@/config-utils";
 import { hasChartConfigs } from "@/configurator";
 import { TimeSlider } from "@/configurator/interactive-filters/time-slider";
 import { useConfiguratorState } from "@/src";

diff --git a/app/charts/column/columns-grouped-state-props.ts b/app/charts/column/columns-grouped-state-props.ts
@@ -22,8 +22,9 @@ import {
   useSegmentVariables,
 } from "@/charts/shared/chart-state";
 import { useRenderingKeyVariable } from "@/charts/shared/rendering-utils";
-import { ColumnConfig, useChartConfigFilters } from "@/configurator";
-import { Observation, isTemporalEntityDimension } from "@/domain/data";
+import { useChartConfigFilters } from "@/config-utils";
+import { ColumnConfig } from "@/configurator";
+import { isTemporalEntityDimension, Observation } from "@/domain/data";
 import { sortByIndex } from "@/utils/array";
 
 import { ChartProps } from "../shared/ChartProps";

diff --git a/app/charts/column/columns-stacked-state-props.ts b/app/charts/column/columns-stacked-state-props.ts
@@ -19,8 +19,9 @@ import {
   useSegmentVariables,
 } from "@/charts/shared/chart-state";
 import { useRenderingKeyVariable } from "@/charts/shared/rendering-utils";
-import { ColumnConfig, useChartConfigFilters } from "@/configurator";
-import { Observation, isTemporalEntityDimension } from "@/domain/data";
+import { useChartConfigFilters } from "@/config-utils";
+import { ColumnConfig } from "@/configurator";
+import { isTemporalEntityDimension, Observation } from "@/domain/data";
 import { sortByIndex } from "@/utils/array";
 
 import { ChartProps } from "../shared/ChartProps";

diff --git a/app/charts/column/columns-state-props.ts b/app/charts/column/columns-state-props.ts
@@ -19,7 +19,8 @@ import {
   useNumericalYVariables,
 } from "@/charts/shared/chart-state";
 import { useRenderingKeyVariable } from "@/charts/shared/rendering-utils";
-import { ColumnConfig, useChartConfigFilters } from "@/configurator";
+import { useChartConfigFilters } from "@/config-utils";
+import { ColumnConfig } from "@/configurator";
 import { isTemporalEntityDimension } from "@/domain/data";
 
 import { ChartProps } from "../shared/ChartProps";

diff --git a/app/charts/combo/combo-line-column-state-props.ts b/app/charts/combo/combo-line-column-state-props.ts
@@ -12,15 +12,16 @@ import {
   ChartStateData,
   InteractiveFiltersVariables,
   RenderingVariables,
-  SortingVariables,
   shouldUseDynamicMinScaleValue,
+  SortingVariables,
   useBandXVariables,
   useBaseVariables,
   useChartData,
   useInteractiveFiltersVariables,
 } from "@/charts/shared/chart-state";
 import { useRenderingKeyVariable } from "@/charts/shared/rendering-utils";
-import { ComboLineColumnConfig, useChartConfigFilters } from "@/configurator";
+import { useChartConfigFilters } from "@/config-utils";
+import { ComboLineColumnConfig } from "@/configurator";
 
 import { ChartProps } from "../shared/ChartProps";
 

diff --git a/app/charts/index.ts b/app/charts/index.ts
@@ -16,24 +16,26 @@ import {
   getDefaultCategoricalColorField,
   getDefaultNumericalColorField,
 } from "@/charts/map/constants";
+import {
+  ChartConfigsAdjusters,
+  FieldAdjuster,
+  InteractiveFiltersAdjusters,
+} from "@/config-adjusters";
 import {
   AreaSegmentField,
   canBeNormalized,
   ChartConfig,
-  ChartConfigsAdjusters,
   ChartSegmentField,
   ChartType,
   ColumnSegmentField,
   ComboChartType,
   ComboLineColumnFields,
   ComboLineSingleFields,
   Cube,
-  FieldAdjuster,
   Filters,
   GenericField,
   GenericFields,
   GenericSegmentField,
-  InteractiveFiltersAdjusters,
   InteractiveFiltersConfig,
   isAreaConfig,
   isColumnConfig,

diff --git a/app/charts/map/chart-map.tsx b/app/charts/map/chart-map.tsx
@@ -11,12 +11,13 @@ import {
   ChartControlsContainer,
 } from "@/charts/shared/containers";
 import { NoGeometriesHint } from "@/components/hint";
-import { Cube, MapConfig, useChartConfigFilters } from "@/config-types";
+import { Cube, MapConfig } from "@/config-types";
+import { useChartConfigFilters } from "@/config-utils";
 import { TimeSlider } from "@/configurator/interactive-filters/time-slider";
 import {
+  dimensionValuesToGeoCoordinates,
   GeoCoordinates,
   GeoShapes,
-  dimensionValuesToGeoCoordinates,
 } from "@/domain/data";
 import { useDataCubesComponentsQuery } from "@/graphql/hooks";
 import { getResolvedJoinById, isJoinById } from "@/graphql/join";
@@ -180,6 +181,7 @@ const ChartMap = memo((props: ChartMapProps) => {
   const { chartConfig, dimensions, observations } = props;
   const { fields } = chartConfig;
   const filters = useChartConfigFilters(chartConfig);
+
   return (
     <MapChart {...props}>
       <ChartContainer>

diff --git a/app/charts/map/map-state-props.ts b/app/charts/map/map-state-props.ts
@@ -16,7 +16,8 @@ import {
   useBaseVariables,
   useChartData,
 } from "@/charts/shared/chart-state";
-import { MapConfig, useChartConfigFilters } from "@/configurator";
+import { useChartConfigFilters } from "@/config-utils";
+import { MapConfig } from "@/configurator";
 import {
   GeoData,
   GeoPoint,

diff --git a/app/charts/pie/chart-pie.tsx b/app/charts/pie/chart-pie.tsx
@@ -11,7 +11,8 @@ import {
 import { Tooltip } from "@/charts/shared/interaction/tooltip";
 import { LegendColor } from "@/charts/shared/legend-color";
 import { OnlyNegativeDataHint } from "@/components/hint";
-import { PieConfig, useChartConfigFilters } from "@/config-types";
+import { PieConfig } from "@/config-types";
+import { useChartConfigFilters } from "@/config-utils";
 import { TimeSlider } from "@/configurator/interactive-filters/time-slider";
 
 import { ChartProps, VisualizationProps } from "../shared/ChartProps";

diff --git a/app/charts/pie/pie-state-props.ts b/app/charts/pie/pie-state-props.ts
@@ -11,7 +11,8 @@ import {
   useSegmentVariables,
 } from "@/charts/shared/chart-state";
 import { useRenderingKeyVariable } from "@/charts/shared/rendering-utils";
-import { PieConfig, useChartConfigFilters } from "@/configurator";
+import { useChartConfigFilters } from "@/config-utils";
+import { PieConfig } from "@/configurator";
 
 import { ChartProps } from "../shared/ChartProps";
 

diff --git a/app/charts/scatterplot/chart-scatterplot.tsx b/app/charts/scatterplot/chart-scatterplot.tsx
@@ -19,7 +19,8 @@ import {
 import { Tooltip } from "@/charts/shared/interaction/tooltip";
 import { LegendColor } from "@/charts/shared/legend-color";
 import { InteractionVoronoi } from "@/charts/shared/overlay-voronoi";
-import { ScatterPlotConfig, useChartConfigFilters } from "@/config-types";
+import { ScatterPlotConfig } from "@/config-types";
+import { useChartConfigFilters } from "@/config-utils";
 import { TimeSlider } from "@/configurator/interactive-filters/time-slider";
 
 import { ChartProps, VisualizationProps } from "../shared/ChartProps";
@@ -35,6 +36,7 @@ const ChartScatterplot = memo((props: ChartProps<ScatterPlotConfig>) => {
   const { chartConfig, dimensions } = props;
   const { fields, interactiveFiltersConfig } = chartConfig;
   const filters = useChartConfigFilters(chartConfig);
+
   return (
     <ScatterplotChart {...props}>
       <ChartContainer>

diff --git a/app/charts/scatterplot/scatterplot-state-props.ts b/app/charts/scatterplot/scatterplot-state-props.ts
@@ -13,7 +13,8 @@ import {
   useSegmentVariables,
 } from "@/charts/shared/chart-state";
 import { useRenderingKeyVariable } from "@/charts/shared/rendering-utils";
-import { ScatterPlotConfig, useChartConfigFilters } from "@/configurator";
+import { useChartConfigFilters } from "@/config-utils";
+import { ScatterPlotConfig } from "@/configurator";
 
 import { ChartProps } from "../shared/ChartProps";
 

diff --git a/app/charts/shared/chart-data-filters.tsx b/app/charts/shared/chart-data-filters.tsx
@@ -18,6 +18,7 @@ import { Select } from "@/components/form";
 import { Loading } from "@/components/hint";
 import { OpenMetadataPanelWrapper } from "@/components/metadata-panel";
 import SelectTree, { Tree } from "@/components/select-tree";
+import { useChartConfigFilters } from "@/config-utils";
 import {
   areDataFiltersActive,
   ChartConfig,
@@ -26,7 +27,6 @@ import {
   Filters,
   getFiltersByMappingStatus,
   SingleFilters,
-  useChartConfigFilters,
   useConfiguratorState,
 } from "@/configurator";
 import { FieldLabel, LoadingIndicator } from "@/configurator/components/field";

diff --git a/app/charts/shared/chart-helpers.tsx b/app/charts/shared/chart-helpers.tsx
@@ -20,12 +20,12 @@ import {
   InteractiveFiltersTimeRange,
   MapConfig,
 } from "@/config-types";
+import { getChartConfigFilters } from "@/config-utils";
 import {
   CategoricalColorField,
   ComboChartConfig,
   DashboardFiltersConfig,
   GenericField,
-  getChartConfigFilters,
   isComboChartConfig,
   NumericalColorField,
 } from "@/configurator";

diff --git a/app/charts/shared/containers.tsx b/app/charts/shared/containers.tsx
@@ -6,8 +6,8 @@ import { ReactNode, useEffect, useRef } from "react";
 import { useChartState } from "@/charts/shared/chart-state";
 import { CalculationToggle } from "@/charts/shared/interactive-filter-calculation-toggle";
 import { useObserverRef } from "@/charts/shared/use-size";
+import { getChartConfig } from "@/config-utils";
 import {
-  getChartConfig,
   hasChartConfigs,
   isLayoutingFreeCanvas,
   useConfiguratorState,

diff --git a/app/charts/shared/legend-color.tsx b/app/charts/shared/legend-color.tsx
@@ -13,21 +13,21 @@ import { Checkbox, CheckboxProps } from "@/components/form";
 import { MaybeTooltip } from "@/components/maybe-tooltip";
 import { OpenMetadataPanelWrapper } from "@/components/metadata-panel";
 import { TooltipTitle } from "@/components/tooltip-utils";
+import { useChartConfigFilters } from "@/config-utils";
 import {
   ChartConfig,
   GenericSegmentField,
-  MapConfig,
   isSegmentInConfig,
-  useChartConfigFilters,
+  MapConfig,
   useReadOnlyConfiguratorState,
 } from "@/configurator";
 import {
   Component,
   Dimension,
-  Measure,
-  Observation,
   isOrdinalDimension,
   isOrdinalMeasure,
+  Measure,
+  Observation,
 } from "@/domain/data";
 import SvgIcChevronRight from "@/icons/components/IcChevronRight";
 import { useChartInteractiveFilters } from "@/stores/interactive-filters";

diff --git a/app/charts/shared/use-sync-interactive-filters.tsx b/app/charts/shared/use-sync-interactive-filters.tsx
@@ -5,8 +5,8 @@ import {
   DashboardFiltersConfig,
   FilterValueSingle,
   isSegmentInConfig,
-  useChartConfigFilters,
 } from "@/config-types";
+import { useChartConfigFilters } from "@/config-utils";
 import { parseDate } from "@/configurator/components/ui-helpers";
 import { FIELD_VALUE_NONE } from "@/configurator/constants";
 import useFilterChanges from "@/configurator/use-filter-changes";

diff --git a/app/components/chart-preview.tsx b/app/components/chart-preview.tsx
@@ -51,10 +51,10 @@ import {
   MetadataPanelStoreContext,
 } from "@/components/metadata-panel-store";
 import { BANNER_MARGIN_TOP } from "@/components/presence";
+import { getChartConfig } from "@/config-utils";
 import {
   ChartConfig,
   DataSource,
-  getChartConfig,
   hasChartConfigs,
   isConfiguring,
   Layout,

diff --git a/app/components/chart-published.tsx b/app/components/chart-published.tsx
@@ -31,11 +31,11 @@ import {
   createMetadataPanelStore,
   MetadataPanelStoreContext,
 } from "@/components/metadata-panel-store";
+import { getChartConfig } from "@/config-utils";
 import {
   ChartConfig,
   ConfiguratorStatePublished,
   DataSource,
-  getChartConfig,
   isPublished,
   useConfiguratorState,
 } from "@/configurator";

diff --git a/app/components/chart-selection-tabs.tsx b/app/components/chart-selection-tabs.tsx
@@ -19,12 +19,12 @@ import { DragHandle } from "@/components/drag-handle";
 import Flex from "@/components/flex";
 import { MenuActionItem } from "@/components/menu-action-item";
 import { VisualizeTab, VisualizeTabList } from "@/components/tabs";
+import { getChartConfig } from "@/config-utils";
 import {
   ChartConfig,
   ChartType,
   ConfiguratorStatePublished,
   ConfiguratorStateWithChartConfigs,
-  getChartConfig,
   hasChartConfigs,
   isConfiguring,
   isLayouting,