(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Raster

Overview

• The Raster Component is an interactive grid-based visualization tool.
• It overlays a coordinate system on top of a background image.
• Users can select and highlight individual grid sections.
• It is useful for seat selection, warehouse mapping, or other position-based selection tasks.

Specs

Tokens

Structure

(Configured in General Properties)

• displayName – Sets the display name of the component shown in the structure panel. For example, "Warehouse Layout" allows for easy identification of the component's purpose in the component structure, making it easier for developers to work with this specific raster component.

(Configured in Visual Properties)

• image – Specifies the URL of the background image over which the raster grid will be displayed. For example, setting it to "https://example.com/images/warehouse-layout.jpg" will show a warehouse floor plan as the background for the grid system.

(Configured in Datasource)

• dataSourceId – Specifies the data source ID for retrieving raster selection data. For example, setting to "api/warehouse/sections" connects the raster to an API endpoint that provides information about which grid sections should be marked as selected.
• datasourceParametersMap – Configures HTTP parameters for data fetching. This object maps parameters needed for the data request, supporting QUERY, PATH, HEADER, and BODY parameter types. For example, {"warehouseId": {"value": "123", "type": "PATH"}} would include the warehouse ID in the path when fetching data.

(Configured in Visibility)

• displayConditions – Defines conditions for displaying the component. This allows showing or hiding the raster based on complex rules involving other form values, user roles, or application state, useful for conditional presentation of the raster component.

Styling

(Configured in Visual Properties)

• paddingClass – Configures spacing around the raster component using CSS classes. For example, "p-4" adds medium padding on all sides of the component, improving its visual integration within its container.

Height & Width

(Configured in Visual Properties)

• rasterHeight – Sets the overall height of the raster component in pixels. For example, setting it to "500" creates a raster with a height of 500 pixels, ensuring consistent sizing across different display environments.
• rasterWidth – Sets the overall width of the raster component in pixels. For example, setting it to "500" creates a raster with a width of 500 pixels, maintaining proper proportions with the specified height.
• rectSize - Defines the size of each individual grid cell in the raster. For example, setting it to "50" creates cells that are 50 pixels tall and wide, affecting both the granularity of selection and the visual appearance.
• enableRaster – Controls whether the raster grid is visible over the background image. When set to true, the coordinate grid is displayed over the image; when false, only the image is shown without grid lines, useful for toggling between view and selection modes.

Color

(Configured in Visual Properties)

• axisTextColor – Sets the color of the axis labels (coordinates) in the raster grid. For example, setting it to "#98989C" creates light gray labels for the grid coordinates, providing visual reference without being too obtrusive.
• rectBackgroundColor – Determines the background color of selected grid cells. For example, setting it to "#E6E14F" (yellow) makes selected cells stand out with a bright yellow background, making selections clearly visible to users.
• textColor – Sets the color of text displayed within selected grid cells. For example, setting it to "#000000" (black) ensures that any text in the selected cells is clearly readable against the cell background color.

Actions & Variants

(Configured in Events)

• events – Configures the events that the component can trigger and respond to.
• ON_RASTER_CLICK – Triggered when a grid cell in the raster is clicked. The event context includes the coordinates and selection state of the clicked cell, enabling actions like recording seat selections or toggling warehouse bin status.
• ON_INIT – Triggered when the raster component is initialized. Can be used to perform setup operations like loading default selections.
• ON_DESTROY – Triggered when the raster component is removed from the DOM. Useful for cleanup operations and releasing resources.

The Dynamic Raster Component provides several programmatic actions that can be triggered through flows or other components:

• getData – Retrieves the current selection data from the raster, returning an array of selected grid coordinates. This is useful for saving the current state or passing selections to other components.
• clearData – Removes all selections from the raster, resetting it to a blank state. This is useful for implementing a "clear all selections" feature.
• reloadData – Refreshes the raster data from the configured data source, useful when the underlying data may have changed due to actions outside the component.
• toggleRasterOn – Enables the display of the grid lines over the background image, making the coordinate system visible.
• toggleRasterOff – Disables the display of the grid lines, showing only the background image with selections, for a cleaner visual presentation.
• getRasterState – Returns the current visibility state of the raster grid lines, useful for UI controls that need to reflect the current display mode.

Tests

(Configured in Testing Hooks)

• id – Specifies a unique identifier for the component used for programmatic access. For example, "warehouseRaster" enables targeted manipulation of this specific raster component.
• dataTestId – Sets the testing hook ID for automated testing. For example, setting it to "warehouse-section-raster" allows test scripts to reliably locate this component during automated testing.
• enableAsHotspot – Enables the component as a guided tour hotspot. When enabled, the raster can be highlighted during onboarding or tutorial flows to explain its functionality to new users.
• guidedTourHotSpotTitle – Sets the title for the guided tour hotspot, supporting translations. For example, {"en-US": "Section Selection", "de-DE": "Bereichsauswahl"} provides clear identification during guided tours.
• guidedTourHotSpotDescription – Sets the description for the guided tour hotspot, supporting translations. For example, {"en-US": "Click on sections to select/deselect them", "de-DE": "Klicken Sie auf Bereiche, um sie auszuwählen/abzuwählen"} provides detailed instructions during guided tours.

Authorization

(Configured in Authorization)

• visibilityPolicySetId – Determines the visibility of the component based on specified policy sets. For example, setting to "warehouseManagersOnly" restricts the raster visibility to users with warehouse manager privileges, ensuring that only authorized personnel can view or modify the raster selections.

Links

• Figme: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11613-71930&t=ftfrOGkPzlG2GaTo-1
• Live style guide: https://e1-dev.k8s.myapp.de/live-style-guide/id7/6-image-raster

Guidelines

Usage

• Use Raster to enable position-based selection over a fixed image such as seating maps or warehouse layouts; bind the background via image and make the grid visible with enableRaster.
• Use for discrete, cell-level selections (not free-form drawing). Handle taps/clicks with events.ON_RASTER_CLICK and persist/hand off selections using getData.
• Keep the component present only when needed using displayConditions (state-driven show/hide) or visibilityPolicySetId (role-gated availability).

Sizing & Layout

• Size the drawing plane explicitly so the grid aligns with the image: set rasterWidth/rasterHeight and define cell size with rectSize (square) or rectW/rectH (rectangular).
• Prefer cell sizes that map cleanly to the underlying image scale to avoid misalignment and accidental multi-cell hits. Configure via rectSize or rectW/rectH.
• Add outer breathing room only via the component’s own paddingClass.

States & Feedback

• Represent selection state with the visual tokens: use rectBackgroundColor for selected cells and ensure any cell text remains readable via textColor.
• Expose/Hide grid lines to indicate mode shifts (e.g., view vs. select) using toggleRasterOn/toggleRasterOff; read current mode with getRasterState.

Color & Contrast

• Ensure axis labels are legible over the image by choosing an axisTextColor with sufficient contrast against the background.
• Maintain readable selection overlays by pairing rectBackgroundColor with a contrasting textColor.
• On busy images, turn grid lines on (toggleRasterOn) to aid targeting.

Visibility & Authorization

• Gate visibility by role/policy using visibilityPolicySetId.
• Use displayConditions to show/hide based on page state (e.g., show only after an image is available or a location is selected).

Content & Localization

• Name the component clearly for authors via displayName so it’s easy to find and maintain in large structures.

Dos & Don’ts

Accessibility

• Provide stable automation and testing hooks via dataTestId (and id for programmatic access).
• Optional guided tour hotspot can surface inline instructions; localize copy with guidedTourHotSpotTitle and guidedTourHotSpotDescription.
  • When using the guided tour hotspot, keep title/description concise and provide translations via guidedTourHotSpotTitle/guidedTourHotSpotDescription.
• Expose dataTestId consistently so automated accessibility checks can target the component reliably.