@opentrons/components 0.1.7-alpha.0 → 0.2.0-alpha.0

package/src/hardware-sim/Labware/CalibrationBlockRender.tsx

@@ -0,0 +1,172 @@
+import { getLabwareViewBox } from '@opentrons/shared-data'
+
+import {
+  C_MED_DARK_GRAY,
+  C_MED_GRAY,
+  C_MED_LIGHT_GRAY,
+  FONT_WEIGHT_SEMIBOLD,
+  RobotCoordsText,
+  TYPOGRAPHY,
+} from '../..'
+
+import type { LabwareDefinition } from '@opentrons/shared-data'
+
+// These strings match what's physically etched on the calibration block,
+// so they probably shouldn't be localized.
+const SHORT = 'SHORT'
+const TALL = 'TALL'
+
+const TEXT_MARGIN = 5
+
+interface CalibrationBlockRenderProps {
+  /**
+   * Must be a calibration block definition, e.g.
+   * opentrons_calibrationblock_short_side_left or ..._short_side_right.
+   */
+  labwareDef: LabwareDefinition
+}
+
+/**
+ * Render a top-down view of an OT-2 calibration block. This displays features specific
+ * to calibration blocks, which the more general <Labware> component doesn't know
+ * about.
+ */
+export function CalibrationBlockRender(
+  props: CalibrationBlockRenderProps
+): JSX.Element | null {
+  const { labwareDef } = props
+  const { minX, minY, xDimension, yDimension } = getLabwareViewBox(labwareDef)
+  const textLeftX = minX + TEXT_MARGIN
+  const textRightX = minX + xDimension - TEXT_MARGIN
+  const textY = minY + yDimension / 2
+
+  switch (labwareDef.parameters.loadName) {
+    case 'opentrons_calibrationblock_short_side_right': {
+      return (
+        <>
+          <rect
+            width={xDimension}
+            height={yDimension}
+            rx="10"
+            ry="10"
+            x={minX}
+            y={minY}
+            fill={C_MED_DARK_GRAY}
+          />
+          <rect
+            width={xDimension / 2}
+            height={yDimension}
+            rx="10"
+            ry="10"
+            x={minX}
+            y={minY}
+            fill={C_MED_GRAY}
+          />
+          <g
+            transform={`rotate(
+              270,
+              ${textLeftX},
+              ${textY}
+            )`}
+          >
+            <RobotCoordsText
+              x={textLeftX}
+              y={textY}
+              textAnchor="middle"
+              fill={C_MED_LIGHT_GRAY}
+              fontSize={TYPOGRAPHY.fontSizeCaption}
+              fontWeight={FONT_WEIGHT_SEMIBOLD}
+            >
+              {TALL}
+            </RobotCoordsText>
+          </g>
+          <g
+            transform={`rotate(
+              90,
+              ${textRightX},
+              ${textY}
+            )`}
+          >
+            <RobotCoordsText
+              x={textRightX}
+              y={textY}
+              textAnchor="middle"
+              fill={C_MED_LIGHT_GRAY}
+              fontSize={TYPOGRAPHY.fontSizeCaption}
+              fontWeight={FONT_WEIGHT_SEMIBOLD}
+            >
+              {SHORT}
+            </RobotCoordsText>
+          </g>
+        </>
+      )
+    }
+    case 'opentrons_calibrationblock_short_side_left': {
+      return (
+        <>
+          <rect
+            width={xDimension}
+            height={yDimension}
+            rx="10"
+            ry="10"
+            x={minX}
+            y={minY}
+            fill={C_MED_DARK_GRAY}
+          />
+          <rect
+            width={xDimension / 2}
+            height={yDimension}
+            rx="10"
+            ry="10"
+            x={minX + xDimension / 2}
+            y={minY}
+            fill={C_MED_GRAY}
+          />
+          <g
+            transform={`rotate(
+              270,
+              ${textLeftX},
+              ${textY}
+            )`}
+          >
+            <RobotCoordsText
+              x={textLeftX}
+              y={textY}
+              textAnchor="middle"
+              fill={C_MED_LIGHT_GRAY}
+              fontSize={TYPOGRAPHY.fontSizeCaption}
+              fontWeight={FONT_WEIGHT_SEMIBOLD}
+            >
+              {SHORT}
+            </RobotCoordsText>
+          </g>
+          <g
+            transform={`rotate(
+              90,
+              ${textRightX},
+              ${textY}
+            )`}
+          >
+            <RobotCoordsText
+              x={textRightX}
+              y={textY}
+              textAnchor="middle"
+              fill={C_MED_LIGHT_GRAY}
+              fontSize={TYPOGRAPHY.fontSizeCaption}
+              fontWeight={FONT_WEIGHT_SEMIBOLD}
+            >
+              {TALL}
+            </RobotCoordsText>
+          </g>
+        </>
+      )
+    }
+    default: {
+      // should never reach this case
+      console.warn(
+        '<CalibrationBlockRender> given a non-calibration-block labware definition. Rendering nothing.'
+      )
+      return null
+    }
+  }
+}

package/src/hardware-sim/Labware/Labware.tsx

@@ -1,32 +1,37 @@
 import { Fragment, memo } from 'react'
-import styled from 'styled-components'
 import map from 'lodash/map'
+import styled from 'styled-components'
 
-import { COLORS } from '../../helix-design-system'
+import {
+  getSchema2CornerOffsetFromSlot,
+  getSchema2Dimensions,
+} from '@opentrons/shared-data'
 
+import { COLORS } from '../../helix-design-system'
+import { LabwareAdapter, labwareAdapterLoadNames } from './LabwareAdapter'
 import {
   LabwareOutline,
   LabwareWellLabels,
   STYLE_BY_WELL_CONTENTS,
   Well,
 } from './labwareInternals'
-import { LabwareAdapter, labwareAdapterLoadNames } from './LabwareAdapter'
 
-import type { LabwareDefinition2, LabwareWell } from '@opentrons/shared-data'
+import type { RefObject } from 'react'
+import type { LabwareDefinition, LabwareWell } from '@opentrons/shared-data'
+import type { LabwareAdapterLoadName } from './LabwareAdapter'
 import type {
   HighlightedWellLabels,
-  WellMouseEvent,
   WellFill,
+  WellMouseEvent,
   WellStroke,
 } from './labwareInternals/types'
 
-import type { RefObject } from 'react'
-import type { LabwareAdapterLoadName } from './LabwareAdapter'
-
 export interface LabwareProps {
   /** Labware definition to render */
-  definition: LabwareDefinition2
-  /** Opional Prop for labware on heater shakers sitting on right side of the deck */
+  definition: LabwareDefinition
+  /* See docs on LabwareRender. */
+  positioningMode: 'passThrough' | 'offsetInSlot'
+  /** See docs on LabwareRender. */
   shouldRotateAdapterOrientation?: boolean
   /** boolean to show well labels */
   showLabels?: boolean
@@ -77,15 +82,14 @@ const LabwareDetailGroup = styled.g`
 `
 
 /**
- * a refactor of the legacy LabwareRender component intended to provide predictable styling
- * initial use in ODD well selection component with ODD-specific well label styling
- * consider adding additional styled wells props if used elsewhere
- * @param props
- * @returns
+ * Similar to the LabwareRender component, but with ODD-specific styling.
+ *
+ * For example, hiding the outline of the labware for certain ODD flows.
  */
 export const Labware = (props: LabwareProps): JSX.Element => {
   const {
     definition,
+    positioningMode,
     gRef,
     hideOutline = false,
     highlight,
@@ -100,23 +104,28 @@ export const Labware = (props: LabwareProps): JSX.Element => {
     wellStroke = {},
   } = props
 
-  const cornerOffsetFromSlot = definition.cornerOffsetFromSlot
+  const cornerOffsetFromSlot = getSchema2CornerOffsetFromSlot(definition)
   const labwareLoadName = definition.parameters.loadName
+  const isAdapter = labwareAdapterLoadNames.includes(labwareLoadName)
 
-  if (labwareAdapterLoadNames.includes(labwareLoadName)) {
+  if (isAdapter) {
     const { shouldRotateAdapterOrientation = false } = props
-    const { xDimension, yDimension } = definition.dimensions
+    const { xDimension, yDimension } = getSchema2Dimensions(definition)
 
     return (
       <g
         transform={
-          shouldRotateAdapterOrientation
+          positioningMode === 'offsetInSlot' && shouldRotateAdapterOrientation
             ? `rotate(180, ${xDimension / 2}, ${yDimension / 2})`
-            : 'rotate(0, 0, 0)'
+            : undefined
         }
       >
         <g
-          transform={`translate(${cornerOffsetFromSlot.x}, ${cornerOffsetFromSlot.y})`}
+          transform={
+            positioningMode === 'offsetInSlot'
+              ? `translate(${cornerOffsetFromSlot.x}, ${cornerOffsetFromSlot.y})`
+              : undefined
+          }
           ref={gRef}
         >
           <LabwareAdapter
@@ -131,7 +140,11 @@ export const Labware = (props: LabwareProps): JSX.Element => {
 
   return (
     <g
-      transform={`translate(${cornerOffsetFromSlot.x}, ${cornerOffsetFromSlot.y})`}
+      transform={
+        positioningMode === 'offsetInSlot'
+          ? `translate(${cornerOffsetFromSlot.x}, ${cornerOffsetFromSlot.y})`
+          : undefined
+      }
       ref={gRef}
     >
       <g onClick={onLabwareClick}>

package/src/hardware-sim/Labware/LabwareAdapter/index.tsx

@@ -1,13 +1,14 @@
+import { COLORS } from '../../../helix-design-system'
+import { LabwareOutline } from '../labwareInternals'
 import { Opentrons96DeepWellAdapter } from './Opentrons96DeepWellAdapter'
 import { Opentrons96FlatBottomAdapter } from './Opentrons96FlatBottomAdapter'
-import { OpentronsUniversalFlatAdapter } from './OpentronsUniversalFlatAdapter'
 import { OpentronsAluminumFlatBottomPlate } from './OpentronsAluminumFlatBottomPlate'
+import { OpentronsAutoclavableDeckRiser } from './OpentronsAutoclavableDeckRiser'
 import { OpentronsFlex96TiprackAdapter } from './OpentronsFlex96TiprackAdapter'
 import { OpentronsToughPCRAutoSealingLid } from './OpentronsToughPCRAutoSealingLid'
-import { OpentronsAutoclavableDeckRiser } from './OpentronsAutoclavableDeckRiser'
-import { COLORS } from '../../../helix-design-system'
-import { LabwareOutline } from '../labwareInternals'
-import type { LabwareDefinition2 } from '@opentrons/shared-data'
+import { OpentronsUniversalFlatAdapter } from './OpentronsUniversalFlatAdapter'
+
+import type { LabwareDefinition } from '@opentrons/shared-data'
 
 const LABWARE_ADAPTER_LOADNAME_PATHS = {
   opentrons_96_deep_well_adapter: Opentrons96DeepWellAdapter,
@@ -26,7 +27,7 @@ export const labwareAdapterLoadNames = Object.keys(
 
 export interface LabwareAdapterProps {
   labwareLoadName: LabwareAdapterLoadName
-  definition?: LabwareDefinition2
+  definition?: LabwareDefinition
   highlight?: boolean
   highlightShadow?: boolean
 }

package/src/hardware-sim/Labware/LabwareRender.stories.tsx

@@ -1,9 +1,7 @@
-import type * as React from 'react'
-
 import {
-  fixture96Plate as _fixture96Plate,
-  fixture24Tuberack as _fixture24Tuberack,
   fixture12Trough as _fixture12Trough,
+  fixture24Tuberack as _fixture24Tuberack,
+  fixture96Plate as _fixture96Plate,
   fixtureTiprack10ul as _fixtureTiprack10ul,
   fixtureTiprack300ul as _fixtureTiprack300ul,
   fixtureTiprack1000ul as _fixtureTiprack1000ul,
@@ -12,24 +10,25 @@ import {
 import { RobotWorkSpace } from '../Deck'
 import { LabwareRender } from './LabwareRender'
 
-import type { Story, Meta } from '@storybook/react'
-import type { LabwareDefinition2 } from '@opentrons/shared-data'
+import type { Meta, Story } from '@storybook/react'
+import type * as React from 'react'
+import type { LabwareDefinition } from '@opentrons/shared-data'
 
-const fixture96Plate = _fixture96Plate as LabwareDefinition2
-const fixture24Tuberack = _fixture24Tuberack as LabwareDefinition2
-const fixture12Trough = _fixture12Trough as LabwareDefinition2
+const fixture96Plate = _fixture96Plate as LabwareDefinition
+const fixture24Tuberack = _fixture24Tuberack as LabwareDefinition
+const fixture12Trough = _fixture12Trough as LabwareDefinition
 
-const fixtureTiprack10 = _fixtureTiprack10ul as LabwareDefinition2
-const fixtureTiprack300 = _fixtureTiprack300ul as LabwareDefinition2
-const fixtureTiprack1000 = _fixtureTiprack1000ul as LabwareDefinition2
+const fixtureTiprack10 = _fixtureTiprack10ul as LabwareDefinition
+const fixtureTiprack300 = _fixtureTiprack300ul as LabwareDefinition
+const fixtureTiprack1000 = _fixtureTiprack1000ul as LabwareDefinition
 
-const labwareDefMap: Record<string, LabwareDefinition2> = {
+const labwareDefMap: Record<string, LabwareDefinition> = {
   [fixture96Plate.metadata.displayName]: fixture96Plate,
   [fixture24Tuberack.metadata.displayName]: fixture24Tuberack,
   [fixture12Trough.metadata.displayName]: fixture12Trough,
 }
 
-const tipRackDefMap: Record<string, LabwareDefinition2> = {
+const tipRackDefMap: Record<string, LabwareDefinition> = {
   [fixtureTiprack10.metadata.displayName]: fixtureTiprack10,
   [fixtureTiprack300.metadata.displayName]: fixtureTiprack300,
   [fixtureTiprack1000.metadata.displayName]: fixtureTiprack1000,
@@ -52,24 +51,34 @@ const Template: Story<React.ComponentProps<typeof LabwareRender>> = ({
   definition,
   ...args
 }) => {
-  const displayName: unknown = definition
-  const allLabwareMap = { ...labwareDefMap, ...tipRackDefMap }
-  const resolvedDef: typeof definition = allLabwareMap[displayName as string]
-  return <LabwareRender definition={resolvedDef} {...args} />
+  // Ensure we have a valid definition
+  const resolvedDef = definition || fixture96Plate
+  return (
+    <LabwareRender
+      definition={resolvedDef}
+      positioningMode="passThrough"
+      {...args}
+    />
+  )
 }
+
 export const Basic = Template.bind({})
 Basic.argTypes = {
   definition: {
     control: {
       type: 'select',
-      options: Object.keys(labwareDefMap).map(
-        d => labwareDefMap[d].metadata.displayName
-      ),
+      options: Object.keys(labwareDefMap),
+    },
+  },
+  positioningMode: {
+    control: {
+      type: 'select',
+      options: ['passThrough', 'offsetInSlot'],
     },
-    defaultValue: fixture96Plate.metadata.displayName,
   },
 }
 Basic.args = {
+  definition: fixture96Plate,
   wellLabelOption: 'SHOW_LABEL_INSIDE',
   highlightedWells: { A1: null, A2: null },
   wellFill: { A1: 'maroon', A2: 'lavender' },
@@ -81,14 +90,19 @@ TipRack.argTypes = {
   definition: {
     control: {
       type: 'select',
-      options: Object.keys(tipRackDefMap).map(
-        d => tipRackDefMap[d].metadata.displayName
-      ),
+      options: Object.keys(tipRackDefMap),
+    },
+  },
+  positioningMode: {
+    control: {
+      type: 'select',
+      options: ['passThrough', 'offsetInSlot'],
     },
-    defaultValue: fixtureTiprack10.metadata.displayName,
   },
 }
 TipRack.args = {
+  definition: fixtureTiprack10,
+  positioningMode: 'passThrough',
   wellLabelOption: 'SHOW_LABEL_INSIDE',
   highlightedWells: { A1: null, A2: null },
   missingTips: { C3: null, D4: null },

package/src/hardware-sim/Labware/LabwareRender.tsx

@@ -1,25 +1,28 @@
 import {
-  WellLabels,
-  StyledWells,
+  getSchema2CornerOffsetFromSlot,
+  getSchema2Dimensions,
+} from '@opentrons/shared-data'
+
+import { LabwareAdapter, labwareAdapterLoadNames } from './LabwareAdapter'
+import {
   FilledWells,
-  StrokedWells,
   StaticLabware,
+  StrokedWells,
+  StyledWells,
+  WellLabels,
 } from './labwareInternals'
-import { LabwareAdapter, labwareAdapterLoadNames } from './LabwareAdapter'
 
-import type { CSSProperties } from 'styled-components'
-import type { LabwareDefinition2 } from '@opentrons/shared-data'
+import type { CSSProperties, RefObject } from 'react'
+import type { LabwareDefinition } from '@opentrons/shared-data'
+import type { LabwareAdapterLoadName } from './LabwareAdapter'
 import type {
   HighlightedWellLabels,
-  WellMouseEvent,
   WellFill,
-  WellStroke,
   WellGroup,
+  WellMouseEvent,
+  WellStroke,
 } from './labwareInternals/types'
 
-import type { RefObject } from 'react'
-import type { LabwareAdapterLoadName } from './LabwareAdapter'
-
 export const WELL_LABEL_OPTIONS = {
   SHOW_LABEL_INSIDE: 'SHOW_LABEL_INSIDE',
   SHOW_LABEL_OUTSIDE: 'SHOW_LABEL_OUTSIDE',
@@ -29,8 +32,52 @@ export type WellLabelOption = keyof typeof WELL_LABEL_OPTIONS
 
 export interface LabwareRenderProps {
   /** Labware definition to render */
-  definition: LabwareDefinition2
-  /** Opional Prop for labware on heater shakers sitting on right side of the deck */
+  definition: LabwareDefinition
+  /**
+   * How the rendered labware should be positioned. Use `passThrough` for new code.
+   *
+   * `passThrough` -
+   *   The origin of the labware will be at the SVG origin. Beware that what
+   *   "the origin of the labware" corresponds to, physically, is not consistent across
+   *   labware. e.g. do not assume that it's always the labware's front-left corner.
+   *
+   *   To render a labware on its own, use the `getLabwareViewBox()` util from
+   *   shared-data to compute the SVG's viewBox around that origin.
+   *
+   *   To render a labware aligned to something like a deck slot or module, wrap this
+   *   component in an SVG transform. Use a util like shared-data's
+   *   `getDeckSlotOriginToLabwareOrigin()` to compute it.
+   *
+   * `offsetInSlot` -
+   *   The SVG origin will be treated as the origin of the slot enclosing the labware.
+   *   The labware will be offset from that origin according to the labware def's
+   *   cornerOffsetFromSlot.
+   *
+   *   To render a labware on its own, set the SVG viewBox's origin to
+   *   definition.cornerOffsetFromSlot.
+   *
+   *   To render a labware aligned to something like a deck slot or module, wrap this
+   *   component in an SVG transform that places the origin of this component at the
+   *   origin of the slot.
+   *
+   *   This is deprecated because it relies on labware schema 2's slot-centric ideas of
+   *   how labware are positioned. It's also clunky when rendering a labware on its
+   *   own.
+   */
+  // todo(mm, 2025-06-09):
+  // Remove uses of offsetInSlot mode as we're able, and delete it when none are left.
+  positioningMode: 'passThrough' | 'offsetInSlot'
+  /**
+   * Special handling for opentrons_universal_flat_adapter. Unlike other labware,
+   * it rotates to match the underlying module, and that rotation actually matters
+   * because it's asymmetrical.
+   *
+   * This should be true if this is that adapter and we're on the left side of the deck,
+   * and false otherwise.
+   *
+   * Ignored if positioningMode is passThrough, in which case it's the caller's
+   * responsibility to do this rotation.
+   */
   shouldRotateAdapterOrientation?: boolean
   /** option to show well labels inside or outside of labware outline */
   wellLabelOption?: WellLabelOption
@@ -65,28 +112,31 @@ export interface LabwareRenderProps {
 }
 
 export const LabwareRender = (props: LabwareRenderProps): JSX.Element => {
-  const { gRef, definition } = props
+  const { gRef, definition, positioningMode } = props
 
-  const cornerOffsetFromSlot = definition.cornerOffsetFromSlot
+  const cornerOffsetFromSlot = getSchema2CornerOffsetFromSlot(definition)
   const labwareLoadName = definition.parameters.loadName
+  const isAdapter = labwareAdapterLoadNames.includes(labwareLoadName)
 
-  if (labwareAdapterLoadNames.includes(labwareLoadName)) {
+  if (isAdapter) {
     const { shouldRotateAdapterOrientation } = props
-    const { xDimension, yDimension } = props.definition.dimensions
+    const { xDimension, yDimension } = getSchema2Dimensions(definition)
 
     return (
       <g
         transform={
-          shouldRotateAdapterOrientation
+          positioningMode === 'offsetInSlot' && shouldRotateAdapterOrientation
             ? `rotate(180, ${xDimension / 2}, ${yDimension / 2})`
-            : 'rotate(0, 0, 0)'
+            : undefined
         }
       >
         <g
           transform={
-            shouldRotateAdapterOrientation
-              ? `translate(${-cornerOffsetFromSlot.x}, ${-cornerOffsetFromSlot.y})`
-              : `translate(${cornerOffsetFromSlot.x}, ${cornerOffsetFromSlot.y})`
+            positioningMode === 'offsetInSlot'
+              ? shouldRotateAdapterOrientation
+                ? `translate(${-cornerOffsetFromSlot.x}, ${-cornerOffsetFromSlot.y})`
+                : `translate(${cornerOffsetFromSlot.x}, ${cornerOffsetFromSlot.y})`
+              : undefined
           }
           ref={gRef}
           onClick={props.onLabwareClick}
@@ -103,7 +153,11 @@ export const LabwareRender = (props: LabwareRenderProps): JSX.Element => {
   }
   return (
     <g
-      transform={`translate(${cornerOffsetFromSlot.x}, ${cornerOffsetFromSlot.y})`}
+      transform={
+        positioningMode === 'offsetInSlot'
+          ? `translate(${cornerOffsetFromSlot.x}, ${cornerOffsetFromSlot.y})`
+          : undefined
+      }
       ref={gRef}
     >
       <StaticLabware

package/src/hardware-sim/Labware/__tests__/Labware.test.tsx

@@ -1,17 +1,22 @@
-import { describe, it, vi, beforeEach } from 'vitest'
 import { render, screen } from '@testing-library/react'
+import { beforeEach, describe, it, vi } from 'vitest'
+
 import '@testing-library/jest-dom/vitest'
+
 import { fixture12Trough } from '@opentrons/shared-data'
+
+import { Labware } from '../Labware'
 import {
   LabwareOutline,
   LabwareWellLabelsComponent as LabwareWellLabels,
 } from '../labwareInternals'
-import { Labware } from '../Labware'
-import type { LabwareDefinition2 } from '@opentrons/shared-data'
+
+import type { ComponentProps } from 'react'
+import type { LabwareDefinition } from '@opentrons/shared-data'
 
 vi.mock('../labwareInternals')
 
-const troughFixture12 = fixture12Trough as LabwareDefinition2
+const troughFixture12 = fixture12Trough as LabwareDefinition
 
 describe('Labware', () => {
   beforeEach(() => {
@@ -19,7 +24,10 @@ describe('Labware', () => {
   })
 
   it('should render a labware outline', () => {
-    const props = { definition: troughFixture12 }
+    const props: ComponentProps<typeof Labware> = {
+      definition: troughFixture12,
+      positioningMode: 'passThrough',
+    }
     render(
       <svg>
         <Labware {...props} />
@@ -28,8 +36,9 @@ describe('Labware', () => {
     screen.getByText('mock labware outline')
   })
   it('should render well labels', () => {
-    const props = {
+    const props: ComponentProps<typeof Labware> = {
       definition: troughFixture12,
+      positioningMode: 'passThrough',
       showLabels: true,
     }
     vi.mocked(LabwareWellLabels).mockReturnValue(<div>mock well labels</div>)