### Setup and Development Commands (Yarn) Source: https://github.com/visualize-admin/visualization-tool/blob/main/CLAUDE.md Provides essential Yarn commands for setting up the development environment, starting the development server (with and without SSL), and building the embed script during development. ```Bash yarn setup:dev yarn dev yarn dev:ssl yarn dev:rollup ``` -------------------------------- ### Start Development Server Source: https://github.com/visualize-admin/visualization-tool/blob/main/README.md Commands to start the development server. Use `yarn dev:ssl` for HTTPS, which is necessary when working with authentication to avoid SSL errors during redirects. ```sh yarn dev ``` ```sh yarn dev:ssl ``` -------------------------------- ### Setup Development Environment Source: https://github.com/visualize-admin/visualization-tool/blob/main/README.md Command to set up the development environment for the visualization tool. This typically involves initializing dependencies and configurations. ```sh yarn setup:dev ``` -------------------------------- ### Local Development with SSL Source: https://github.com/visualize-admin/visualization-tool/blob/main/README.md Start the local development server with SSL enabled. Ensure the NEXTAUTH_URL environment variable is set to 'https://localhost:3000' in your .env.local file. ```sh yarn dev:ssl ``` -------------------------------- ### Example Configurator State JSON Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/catalog/chart-preview-via-api.mdx This JSON object represents an example state of the configurator, including data set information, data source details, metadata, and chart configuration. It's useful for understanding the structure and potential values used in the visualization tool. ```json { "state": "CONFIGURING_CHART", "dataSet": "https://energy.ld.admin.ch/sfoe/bfe_ogd84_einmalverguetung_fuer_photovoltaikanlagen/7", "dataSource": { "type": "sparql", "url": "https://lindas-cached.cluster.ldbar.ch/query" }, "meta": { "title": { "de": "", "fr": "", "it": "", "en": "" }, "description": { "de": "", "fr": "", "it": "", "en": "" } }, "chartConfig": { "version": "1.4.2", "chartType": "column", "filters": { "https://energy.ld.admin.ch/sfoe/bfe_ogd84_einmalverguetung_fuer_photovoltaikanlagen/Kanton": { "type": "single", "value": "https://ld.admin.ch/canton/1" } }, "interactiveFiltersConfig": { "legend": { "active": false, "componentIri": "" }, "timeRange": { "active": false, "componentIri": "https://energy.ld.admin.ch/sfoe/bfe_ogd84_einmalverguetung_fuer_photovoltaikanlagen/Jahr", "presets": { "type": "range", "from": "", "to": "" } }, "dataFilters": { "active": false, "componentIris": [] }, "calculation": { "active": false, "type": "identity" } }, "fields": { "x": { "componentIri": "https://energy.ld.admin.ch/sfoe/bfe_ogd84_einmalverguetung_fuer_photovoltaikanlagen/Jahr", "sorting": { "sortingType": "byAuto", "sortingOrder": "asc" } }, "y": { "componentIri": "https://energy.ld.admin.ch/sfoe/bfe_ogd84_einmalverguetung_fuer_photovoltaikanlagen/AnzahlAnlagen" } } } } ``` -------------------------------- ### Develop GitHub Actions Locally Source: https://github.com/visualize-admin/visualization-tool/blob/main/README.md Locally build and test GitHub Actions using the 'act' tool. This involves providing mocked event payloads, with examples available in the repository. ```sh act deployment_status -W ".github/workflows/performance-tests-pr.yml" -e act/deployment_status.json ``` -------------------------------- ### Storybook Meta and Canvas Setup Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/dataset-result.docs.mdx Configures Storybook metadata and the Canvas component for rendering the Dataset Result stories. It imports Canvas and Meta from '@storybook/blocks' and references the DatasetResult stories from a local file. ```jsx import { Canvas, Meta } from '@storybook/blocks'; import * as DatasetResultStories from "./dataset-result.stories"; ``` -------------------------------- ### Configure GraphQL k6 Tests Source: https://github.com/visualize-admin/visualization-tool/blob/main/README.md Configure GraphQL tests for k6 by specifying environment variables for the target environment and controlling server-side caching. Use the --env flag for these settings. ```sh k6 run your-script.js --env ENV=(test|int|prod) --env ENABLE_GQL_SERVER_SIDE_CACHE=(true | false) ``` -------------------------------- ### Render Columns Chart (JSX) Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/charts.docs.mdx Renders the Columns chart component using Storybook's Canvas feature. This example assumes a 'Columns' export exists in the 'charts.stories' file. ```jsx ``` -------------------------------- ### Create New Version Source: https://github.com/visualize-admin/visualization-tool/blob/main/README.md Initiate the versioning process by running the yarn version command, which prompts for a new version number. The postversion script automatically pushes the version tag to the origin repository. ```sh yarn version ``` -------------------------------- ### Render Scatterplot Chart (JSX) Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/charts.docs.mdx Renders the Scatterplot chart component using Storybook's Canvas feature. This example assumes a 'Scatterplot' export exists in the 'charts.stories' file. ```jsx ``` -------------------------------- ### Render Line Chart (JSX) Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/charts.docs.mdx Renders the Line chart component using Storybook's Canvas feature. This example assumes a 'Line' export exists in the 'lines.stories' file. ```jsx ``` -------------------------------- ### Run Database Migrations (Development) Source: https://github.com/visualize-admin/visualization-tool/blob/main/README.md Manually run database migrations in a development environment using the provided yarn command. This is necessary as migrations run automatically in production builds. ```sh yarn db:migrate:dev ``` -------------------------------- ### View Visualize Admin Source Code on GitHub Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/static-pages/en/legal-framework.mdx Access the complete source code for the visualize.admin.ch project. This repository contains all the code necessary to understand, modify, or contribute to the visualization tool. ```URL https://github.com/visualize-admin/visualization-tool/ ``` -------------------------------- ### MUI Typography Heading Example Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/typography.docs.mdx This code snippet demonstrates how to use the Material-UI Typography component to render a heading with the 'h1' variant and 'heading1' style. It also shows how to explicitly set the HTML component to 'h1' for semantic correctness. ```jsx import { Text } from "@mui/material" Heading 1 ``` -------------------------------- ### Generate GitHub Actions for k6 Performance Tests Source: https://github.com/visualize-admin/visualization-tool/blob/main/README.md Update GitHub Actions for performance tests by running the codegen command after modifying the generate-github-actions.mjs file. ```sh yarn run github:codegen ``` -------------------------------- ### Database and Migration Commands (Yarn) Source: https://github.com/visualize-admin/visualization-tool/blob/main/CLAUDE.md Covers Yarn commands for managing database migrations, specifically for development environments and production. ```Bash yarn db:migrate:dev yarn db:migrate ``` -------------------------------- ### Homepage Component Integration (JSX) Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/homepage.docs.mdx Demonstrates how to import and use the seven core components of the Visualize app's homepage in a JSX file. Each component is shown with its relevant props for customization. ```jsx import { Contribute, Examples, Intro, Tutorial, Newsletter, BugReport, FeatureRequest } from "../homepage"; ``` -------------------------------- ### Fetch bio-discomap.xml using curl Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/charts/map/mocks/README.md This snippet shows how to fetch the bio-discomap.xml file from the European Environment Agency's WMS server. It includes necessary headers for a successful request, such as User-Agent, Accept, and Referer. ```curl curl \ 'https://bio.discomap.eea.europa.eu/arcgis/services/Ecosystem/Ecosystems/MapServer/WMSServer?SERVICE=WMS&REQUEST=GetCapabilities&VERSION=1.3.0&FORMAT=text%2Fxml&lang=en' \ --compressed -H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15;\n rv:137.0) Gecko/20100101 Firefox/137.0' -H 'Accept: application/json, text/plain, _/_' -H 'Accept-Language: en-US,en;q=0.5' -H 'Accept-Encoding: gzip, deflate, br, zstd' -H 'Origin: https://map.geo.admin.ch' -H 'Connection: keep-alive' -H 'Referer: https://map.geo.admin.ch/' -H 'Sec-Fetch-Dest: empty' -H 'Sec-Fetch-Mode: cors' -H 'Sec-Fetch-Site: cross-site' -H 'Priority: u=0' -H 'Pragma: no-cache' -H 'Cache-Control: no-cache' ``` -------------------------------- ### Run k6 Tests Locally Source: https://github.com/visualize-admin/visualization-tool/blob/main/README.md Execute k6 load tests directly on your local machine. This allows for bypassing cloud limitations and customizing test configurations. Replace 'script-name.js' with the actual test file name. ```sh k6 run k6/script-name.js ``` -------------------------------- ### Access Visualize.admin.ch Source Code on GitHub Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/static-pages/de/rechtliche-grundlagen.mdx The source code for the visualize.admin.ch project is publicly available on GitHub. This link allows developers to access, review, and potentially contribute to the project. ```URL https://github.com/visualize-admin/visualization-tool ``` -------------------------------- ### Enable Debugging and Query Monitoring Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/catalog/testing.mdx Access a page with the `flag__debug=true` query parameter to enable a developer tool for monitoring GraphQL resolver performance and SPARQL queries. A small '🛠' icon will appear, which opens a debug panel showing query timings and collected SPARQL queries. ```url https://test.visualize.admin.ch/en?flag__debug=true ``` -------------------------------- ### Run Snapshot Tests Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/catalog/testing.mdx This command runs snapshot regression tests for the visualization tool. It compares rendered chart images against previous snapshots and fails if differences exceed a threshold. Ensure the app server is running on http://localhost:3000. ```shell yarn test ``` -------------------------------- ### Build and Test Commands (Yarn) Source: https://github.com/visualize-admin/visualization-tool/blob/main/CLAUDE.md Details Yarn commands for performing a full production build, running TypeScript type checking, linting with ESLint, executing unit tests with Vitest (including file-specific and watch modes). ```Bash yarn build yarn typecheck yarn lint yarn test yarn test yarn test:watch ``` -------------------------------- ### Import Chart Selection Tabs and Dependencies Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/chart-selection-tabs.docs.mdx Imports the ChartSelectionTabs component, configuration states, a fixture, and Storybook components for documentation. ```typescript import { ChartSelectionTabs } from "@/components/chart-selection-tabs"; import { ConfiguratorStateConfiguringChart, ConfiguratorStateProvider, } from "@/configurator"; import palmerPenguinsFixture from "@/test/__fixtures/config/int/scatterplot-palmer-penguins.json"; import { Canvas, Meta } from '@storybook/blocks'; import * as ChartSelectionTabsStories from './chart-selection-tabs.stories'; ``` -------------------------------- ### GraphQL and Code Generation Commands (Yarn) Source: https://github.com/visualize-admin/visualization-tool/blob/main/CLAUDE.md Explains Yarn commands for GraphQL code generation, including generating TypeScript types from the schema and running in watch mode. ```Bash yarn graphql:codegen yarn graphql:codegen:dev ``` -------------------------------- ### Update Fixture Snapshots Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/catalog/testing.mdx This script updates the fixture snapshots used for regression testing. It's recommended to run this after ensuring tests are passing and after deleting the `__image_snapshots__` directory for a fresh set of snapshots. ```shell ./scripts/fetch-config-fixtures.js ``` -------------------------------- ### End-to-End Testing Commands (Yarn) Source: https://github.com/visualize-admin/visualization-tool/blob/main/CLAUDE.md Lists Yarn commands for running Playwright end-to-end tests against local development servers, including options for interactive UI and HTTPS. ```Bash yarn e2e:dev yarn e2e:ui yarn e2e:dev:ssl ``` -------------------------------- ### Importing MUI Tabs Components Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/tabs.docs.mdx Imports necessary components for creating and managing tabs, including TabContext, TabList, and Tab from Material-UI, along with custom VisualizeTab components. ```javascript import { TabContext, TabList } from "@mui/lab"; import { Tab } from "@mui/material"; import { useState } from "react"; import { VisualizeTab, VisualizeTabList } from "@/components/tabs"; ``` -------------------------------- ### Manage Translations with Accent CLI Source: https://github.com/visualize-admin/visualization-tool/blob/main/README.md Commands for extracting, pushing, and pulling translation files using the Accent CLI. This includes dry runs for review and options for API key authentication. ```sh yarn locales:extract yarn locales:push --dry-run yarn locales:push yarn locales:browse yarn locales:pull ``` ```sh ACCENT_API_KEY=your_key yarn locales:push ``` -------------------------------- ### Importazione Modelli Email e Componenti UI Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/static-pages/it/index.mdx Importa i modelli di email per segnalazioni di bug, richieste di funzionalità e newsletter, insieme ai componenti UI di Material-UI e funzioni di creazione link email. ```typescript import { bugReportTemplates } from "@/templates/email/bug-report"; import { featureRequestTemplates } from "@/templates/email/feature-request"; import { newsletterTemplates } from "@/templates/email/newsletter"; import { Divider } from "@mui/material"; import { createMailtoLink } from "../../../app/templates/email"; import { OWNER_ORGANIZATION_EMAIL, SUPPORT_EMAIL, } from "../../../app/templates/email/config"; export const contentId = "home"; ``` -------------------------------- ### Import ImageSpecimen Component (JavaScript) Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/typography.mdx Imports the ImageSpecimen component from a local file path. This component is likely used for displaying images within the visualization tool. ```JavaScript import ImageSpecimen from './Image' ``` -------------------------------- ### Fetch geo-admin.wmts.xml using curl Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/charts/map/mocks/README.md This snippet demonstrates how to retrieve the geo-admin.wmts.xml file from the Swiss Federal Office of Topography's WMTS server. It specifies the service, request, version, and language, along with essential headers for the request. ```curl curl 'https://wmts.geo.admin.ch/EPSG/3857/1.0.0/WMTSCapabilities.xml?SERVICE=WMTS&REQUEST=GetCapabilities&lang=en' -H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:137.0) Gecko/20100101 Firefox/137.0' -H 'Accept: application/json, text/plain, */*' -H 'Accept-Language: en-US,en;q=0.5' -H 'Accept-Encoding: gzip, deflate, br, zstd' -H 'Origin: https://map.geo.admin.ch' -H 'Connection: keep-alive' -H 'Referer: https://map.geo.admin.ch/' -H 'Sec-Fetch-Dest: empty' -H 'Sec-Fetch-Mode: cors' -H 'Sec-Fetch-Site: same-site' -H 'Priority: u=0' -H 'Pragma: no-cache' -H 'Cache-Control: no-cache' -H 'TE: trailers' ``` -------------------------------- ### Localization Commands (Yarn) Source: https://github.com/visualize-admin/visualization-tool/blob/main/CLAUDE.md Details Yarn commands for localization tasks, including extracting translatable strings, compiling translation files, and syncing with a translation service. ```Bash yarn locales:extract yarn locales:compile yarn locales:sync ``` -------------------------------- ### Import Icons and Storybook Components Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/icons.docs.mdx Imports necessary components from Storybook for documentation and the Icon component and its types from the local icon module. It also imports icon stories for rendering. ```typescript import { Canvas, Meta } from '@storybook/blocks'; import { Icon, IconName, Icons } from "../icons"; import * as IconStories from './icons.stories'; ``` -------------------------------- ### JavaScript: Iframe Preview via API (postMessage) Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/catalog/chart-preview-via-api.mdx Preview charts by embedding an iframe and communicating the chart state using the postMessage API. This method involves setting up event listeners to send the configuration data to the iframe. ```js const iframe = document.getElementById("chart"); const handleMessage = (e) => { if (e.data?.type === "ready" && e.source === iframe.contentWindow) { iframe.contentWindow?.postMessage(configuratorState, "*"); window.removeEventListener("message", handleMessage); } }; window.addEventListener("message", handleMessage); ``` -------------------------------- ### Import Chart Components (JavaScript/JSX) Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/charts.docs.mdx Imports necessary components and utilities for creating visualizations, including chart types, configuration, and state management. It also imports mock data for testing and Storybook integration. ```javascript import { markdown, ReactSpecimen } from "catalog"; import keyBy from "lodash/keyBy"; import { Columns, ErrorWhiskers } from "@/charts/column/columns"; import { ColumnChart } from "@/charts/column/columns-state"; import { AxisHeightLinear } from "@/charts/shared/axis-height-linear"; import { AxisWidthBand, AxisWidthBandDomain, } from "@/charts/shared/axis-width-band"; import { ChartContainer, ChartSvg } from "@/charts/shared/containers"; import { Tooltip } from "@/charts/shared/interaction/tooltip"; import { ColumnConfig } from "@/configurator"; import { ConfiguratorStateProvider } from "@/configurator/configurator-state"; import { Dimension, Measure } from "@/domain/data"; import { InteractiveFiltersProvider } from "@/stores/interactive-filters"; import { CHART_CONFIG_VERSION, CONFIGURATOR_STATE_VERSION, } from "@/utils/chart-config/versioning"; import { columnDimensions, columnMeasures, columnObservations } from "./columns.mock"; import { Canvas, Meta } from '@storybook/blocks'; import * as ChartStories from './charts.stories'; import * as LineStories from './lines.stories'; ``` -------------------------------- ### Email Link Generation for Newsletter Subscription Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/static-pages/fr/index.mdx Creates a `mailto:` link for newsletter subscriptions. It directs the email to the owner organization's email address and includes a specific template and subject for newsletter sign-ups. ```typescript import { newsletterTemplates } from "@/templates/email/newsletter"; import { createMailtoLink } from "../../../app/templates/email"; import { OWNER_ORGANIZATION_EMAIL, } from "../../../app/templates/email/config"; // ... newsletter: { headline: "S'abonner à notre newsletter", description: "Restez informé et abonnez-vous à notre newsletter.", buttonLabel: "S'abonner", buttonUrl: createMailtoLink("fr", { recipients: { to: OWNER_ORGANIZATION_EMAIL, }, template: newsletterTemplates, subject: "Visualize Newsletter Abonnement", }), } ``` -------------------------------- ### Build Embed Script Source: https://github.com/visualize-admin/visualization-tool/blob/main/README.md Command to build the embed script located at `/dist/embed.js`. This command should be run when changes are made to the source file in `embed/index.ts`. ```sh yarn dev:rollup ``` -------------------------------- ### Display ImageSpecimen Component (HTML/JSX) Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/typography.mdx Renders the ImageSpecimen component with specific props. The 'plain' prop is set to true, and the 'src' prop points to the image file for typography scale. ```JSX ``` -------------------------------- ### HTML: Iframe Preview with Hash Parameters Source: https://github.com/visualize-admin/visualization-tool/blob/main/app/docs/catalog/chart-preview-via-api.mdx Embed a chart preview using an iframe, passing chart state via hash parameters in the URL. This allows for dynamic chart generation and previewing. ```html