@opentrons/components 0.1.7-alpha.1 → 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

@@ -2,6 +2,11 @@ import { Fragment, memo } from 'react'
 import map from 'lodash/map'
 import styled from 'styled-components'
 
+import {
+  getSchema2CornerOffsetFromSlot,
+  getSchema2Dimensions,
+} from '@opentrons/shared-data'
+
 import { COLORS } from '../../helix-design-system'
 import { LabwareAdapter, labwareAdapterLoadNames } from './LabwareAdapter'
 import {
@@ -12,7 +17,7 @@ import {
 } from './labwareInternals'
 
 import type { RefObject } from 'react'
-import type { LabwareDefinition2, LabwareWell } from '@opentrons/shared-data'
+import type { LabwareDefinition, LabwareWell } from '@opentrons/shared-data'
 import type { LabwareAdapterLoadName } from './LabwareAdapter'
 import type {
   HighlightedWellLabels,
@@ -23,8 +28,10 @@ import type {
 
 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
@@ -75,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,
@@ -98,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
@@ -129,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

@@ -8,7 +8,7 @@ import { OpentronsFlex96TiprackAdapter } from './OpentronsFlex96TiprackAdapter'
 import { OpentronsToughPCRAutoSealingLid } from './OpentronsToughPCRAutoSealingLid'
 import { OpentronsUniversalFlatAdapter } from './OpentronsUniversalFlatAdapter'
 
-import type { LabwareDefinition2 } from '@opentrons/shared-data'
+import type { LabwareDefinition } from '@opentrons/shared-data'
 
 const LABWARE_ADAPTER_LOADNAME_PATHS = {
   opentrons_96_deep_well_adapter: Opentrons96DeepWellAdapter,
@@ -27,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

@@ -12,23 +12,23 @@ import { LabwareRender } from './LabwareRender'
 
 import type { Meta, Story } from '@storybook/react'
 import type * as React from 'react'
-import type { LabwareDefinition2 } from '@opentrons/shared-data'
+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,
@@ -51,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' },
@@ -80,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,3 +1,8 @@
+import {
+  getSchema2CornerOffsetFromSlot,
+  getSchema2Dimensions,
+} from '@opentrons/shared-data'
+
 import { LabwareAdapter, labwareAdapterLoadNames } from './LabwareAdapter'
 import {
   FilledWells,
@@ -7,9 +12,8 @@ import {
   WellLabels,
 } from './labwareInternals'
 
-import type { CSSProperties } from 'styled-components'
-import type { RefObject } from 'react'
-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,
@@ -28,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
@@ -64,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}
@@ -102,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

@@ -11,11 +11,12 @@ import {
   LabwareWellLabelsComponent as LabwareWellLabels,
 } from '../labwareInternals'
 
-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(() => {
@@ -23,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} />
@@ -32,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>)

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

@@ -12,11 +12,12 @@ import {
 } from '../labwareInternals'
 import { LabwareRender, WELL_LABEL_OPTIONS } from '../LabwareRender'
 
-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('LabwareRender', () => {
   beforeEach(() => {
@@ -24,7 +25,10 @@ describe('LabwareRender', () => {
   })
 
   it('should render a static labware component', () => {
-    const props = { definition: troughFixture12 }
+    const props: ComponentProps<typeof LabwareRender> = {
+      definition: troughFixture12,
+      positioningMode: 'passThrough',
+    }
     render(
       <svg>
         <LabwareRender {...props} />
@@ -33,7 +37,11 @@ describe('LabwareRender', () => {
     screen.getByText('mock static labware')
   })
   it('should render stroked wells', () => {
-    const props = { definition: troughFixture12, wellStroke: { A1: 'blue' } }
+    const props: ComponentProps<typeof LabwareRender> = {
+      definition: troughFixture12,
+      positioningMode: 'passThrough',
+      wellStroke: { A1: 'blue' },
+    }
     vi.mocked(StrokedWells).mockReturnValue(<div>mock stroked wells</div>)
     render(
       <svg>
@@ -43,8 +51,9 @@ describe('LabwareRender', () => {
     screen.getByText('mock stroked wells')
   })
   it('should render well labels', () => {
-    const props = {
+    const props: ComponentProps<typeof LabwareRender> = {
       definition: troughFixture12,
+      positioningMode: 'passThrough',
       wellLabelOption: WELL_LABEL_OPTIONS.SHOW_LABEL_INSIDE,
     }
     vi.mocked(WellLabels).mockReturnValue(<div>mock well labels</div>)

package/src/hardware-sim/Labware/index.ts

@@ -1,4 +1,5 @@
 export * from './labwareInternals/index'
+export * from './CalibrationBlockRender'
 export * from './LabwareRender'
 export * from './Labware'
 

package/src/hardware-sim/Labware/labware.module.css

@@ -0,0 +1,8 @@
+.adapter_render {
+  transition: transform 0.3s ease;
+}
+
+.rotated {
+  transform: rotate(180deg); /* fallback in case CSS vars not set */
+  transform-origin: var(--cx) var(--cy);
+}

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

@@ -4,12 +4,11 @@ import map from 'lodash/map'
 import { COLORS } from '../../../helix-design-system'
 import { Well } from './Well'
 
-import type { CSSProperties } from 'styled-components'
-import type { MemoExoticComponent, ReactNode } from 'react'
-import type { LabwareDefinition2 } from '@opentrons/shared-data'
+import type { CSSProperties, MemoExoticComponent, ReactNode } from 'react'
+import type { LabwareDefinition } from '@opentrons/shared-data'
 
 export interface FilledWellsProps {
-  definition: LabwareDefinition2
+  definition: LabwareDefinition
   fillByWell: Record<string, CSSProperties['fill']>
   strokeColor?: string
 }