# convert-dimension

## Interface

```typescript
interface parser {
  name: 'convert-dimension';
  options: {
    toFormat:
      | '%' 
      | 'px' 
      | 'em' 
      | 'rem' 
      | 'pt' 
      | 'pc' 
      | 'in' 
      | 'cm' 
      | 'mm' 
      | 'ex' 
      | 'cap' 
      | 'ch' 
      | 'ic' 
      | 'lh' 
      | 'rlh' 
      | 'vw' 
      | 'svw' 
      | 'lvw' 
      | 'dvw' 
      | 'vh' 
      | 'svh' 
      | 'lvh' 
      | 'dvh' 
      | 'vi' 
      | 'svi' 
      | 'lvi' 
      | 'dvi' 
      | 'vb' 
      | 'svb' 
      | 'lvb' 
      | 'dvb' 
      | 'vmin' 
      | 'svmin' 
      | 'lvmin' 
      | 'dvmin' 
      | 'vmax' 
      | 'svmax' 
      | 'lvmax' 
      | 'dvmax'
      | null;
    baseValue?: {
      rem?: number
    };
    applyTo?: SDTFQuery;
    applyToKeys?: {
      textStyle?: Array<'fontSize' | 'lineHeight' | 'letterSpacing' | 'paragraphSpacing'| 'textIndent'>,
      shadow?: Array<'offsetX' | 'offsetY' | 'blurRadius' | 'spreadRadius'>,
      border?: Array<'width' | 'rectangleCornerRadii'>,
    };
    excludeFormats?: array;
    includeFormats?: array;
  };
}
```

## Options

<table><thead><tr><th width="206">Parameter</th><th width="127.33333333333331">Required</th><th width="341">Type</th><th width="136">Default</th><th width="237">Description</th></tr></thead><tbody><tr><td><code>toFormat</code></td><td>required</td><td><pre class="language-typescript"><code class="lang-typescript">| '%' 
| 'px' 
| 'em' 
| 'rem' 
| 'pt' 
| 'pc' 
| 'in' 
| 'cm' 
| 'mm' 
| 'ex' 
| 'cap' 
| 'ch' 
| 'ic' 
| 'lh' 
| 'rlh' 
| 'vw' 
| 'svw' 
| 'lvw' 
| 'dvw' 
| 'vh' 
| 'svh' 
| 'lvh' 
| 'dvh' 
| 'vi' 
| 'svi' 
| 'lvi' 
| 'dvi' 
| 'vb' 
| 'svb' 
| 'lvb' 
| 'dvb' 
| 'vmin' 
| 'svmin' 
| 'lvmin' 
| 'dvmin' 
| 'vmax' 
| 'svmax' 
| 'lvmax' 
| 'dvmax'
| null
</code></pre></td><td></td><td>The target dimension format to convert to.</td></tr><tr><td><code>baseValue</code></td><td><code>false</code></td><td><pre class="language-typescript"><code class="lang-typescript">{ rem: number }
</code></pre></td><td></td><td></td></tr><tr><td><code>applyTo</code></td><td><code>false</code></td><td><pre class="language-typescript"><code class="lang-typescript">| { collection: string | true }
| { group: string | true }
| { token: string | true }
| SDTFQuery
</code></pre></td><td><pre><code>{ token: true }
</code></pre></td><td>The selection where to apply the transformation.<br><br><code>collection</code>, <code>group</code>, <code>token</code> take a Regex string or <code>true</code> to select anything of the kind.<br><br>An <code>SDTFQuery</code> can be used for advance use cases.</td></tr><tr><td><code>applyToKeys</code></td><td><code>false</code></td><td><pre class="language-typescript"><code class="lang-typescript">{
  textStyle?: Array&#x3C;'fontSize' | 'lineHeight' | 'letterSpacing' | 'paragraphSpacing'| 'textIndent'>,
  shadow?: Array&#x3C;'offsetX' | 'offsetY' | 'blurRadius' | 'spreadRadius'>,
  border?: Array&#x3C;'width' | 'rectangleCornerRadii'>,
}
</code></pre></td><td></td><td>Select composite tokens sub-values to convert</td></tr><tr><td><code>excludeFormats</code></td><td><code>false</code></td><td>array</td><td></td><td>List of dimension formats you don't want to convert.</td></tr><tr><td><code>includeFormats</code></td><td><code>false</code></td><td>array</td><td></td><td>List of dimension formats you only want to convert.</td></tr></tbody></table>

## Examples

### Basic usage

{% tabs %}
{% tab title="Input" %}

<pre class="language-json" data-line-numbers><code class="lang-json">{
  "Foundation": {
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
<strong>            "value": 4,
</strong><strong>            "unit": "px"
</strong>          }
        }
      },
      "2": {
        "$type": "dimension",
        "$value": {
          "default": {
<strong>            "value": 8,
</strong><strong>            "unit": "px"
</strong>          }
        }
      },
      "3": {
        "$type": "dimension",
        "$value": {
          "default": {
<strong>            "value": 12,
</strong><strong>            "unit": "px"
</strong>          }
        }
      }
    }
  }
}
</code></pre>

{% endtab %}

{% tab title="Config" %}
We convert all dimensions from our SDTF graph in `rem`.

We then generate our transformed SDTF graph in a JSON file thanks to the [to-sdtf](https://docs.specifyapp.com/reference/parsers/to-sdtf) parser.

{% code title=".specifyrc.json" lineNumbers="true" %}

```json5
{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Convert spacing in rem and generate tokens in JSON",
      "parsers": [
        {
          "name": "convert-dimension",
          "options": {
            "toFormat": "rem"
          }
        },
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "tokens.json"
          }
        }
      ]
    }
  ]
}
```

{% endcode %}
{% endtab %}

{% tab title="Output" %}

<pre class="language-json" data-title="tokens.json" data-line-numbers><code class="lang-json">{
  "Foundation": {
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
<strong>            "value": 0.25,
</strong><strong>            "unit": "rem"
</strong>          }
        }
      },
      "2": {
        "$type": "dimension",
        "$value": {
          "default": {
<strong>            "value": 0.5,
</strong><strong>            "unit": "rem"
</strong>          }
        }
      },
      "3": {
        "$type": "dimension",
        "$value": {
          "default": {
<strong>            "value": 0.75,
</strong><strong>            "unit": "rem"
</strong>          }
        }
      }
    }
  }
}
</code></pre>

{% endtab %}
{% endtabs %}

### Generate unitless dimension tokens

{% tabs %}
{% tab title="Input" %}
{% code lineNumbers="true" %}

```json
{
  "Foundation": {
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 4,
            "unit": "px"
          }
        }
      },
      "2": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 8,
            "unit": "px"
          }
        }
      },
      "3": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 12,
            "unit": "px"
          }
        }
      }
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Config" %}
{% code title=".specifyrc.json" lineNumbers="true" %}

```json
{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Convert spacing in rem and generate tokens in JSON",
      "parsers": [
        {
          "name": "convert-dimension",
          "options": {
            "toFormat": null
          }
        },
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "tokens.json"
          }
        }
      ]
    }
  ]
}
```

{% endcode %}
{% endtab %}

{% tab title="Output" %}

<pre class="language-json" data-title="tokens.json" data-line-numbers><code class="lang-json">{
  "Foundation": {
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 0.25,
<strong>            "unit": null
</strong>          }
        }
      },
      "2": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 0.5,
<strong>            "unit": null
</strong>          }
        }
      },
      "3": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 0.75,
<strong>            "unit": null
</strong>          }
        }
      }
    }
  }
}
</code></pre>

{% endtab %}
{% endtabs %}

### Convert text style's font-size from px to rem

{% tabs %}
{% tab title="Input" %}
{% code lineNumbers="true" %}

```json
{
  "Text styles": {
    "Body": {
      "$type": "textStyle",
      "$value": {
        "default": {
          "font": {
            "family": "Neue Haas Grotesk Text Pro",
            "postScriptName": "Neue Haas Grotesk Text Pro",
            "weight": "roman",
            "style": "normal",
            "files": []
          },
          "fontSize": {
            "value": 14,
            "unit": "px"
          },
          "color": null,
          "fontFeatures": null,
          "lineHeight": {
            "value": 150,
            "unit": "%"
          },
          "letterSpacing": {
            "value": 0.2,
            "unit": "px"
          },
          "paragraphSpacing": {
            "value": 0,
            "unit": "px"
          },
          "textAlignHorizontal": null,
          "textAlignVertical": null,
          "textDecoration": "none",
          "textIndent": {
            "value": 0,
            "unit": "px"
          },
          "textTransform": "none"
        }
      }
    }
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Config" %}
{% code title=".specifyrc.json" lineNumbers="true" %}

```json
{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Convert font-sizes to rem",
      "parsers": [
        {
          "name": "convert-dimension",
          "options": {
            "applyToKeys": {
              "textStyle": [
                "fontSize"
              ]
            },
            "toFormat": "rem"
          }
        },
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "public/tokens.json"
          }
        }
      ]
    }
  ]
}
```

{% endcode %}
{% endtab %}

{% tab title="Output" %}

<pre class="language-json" data-title="tokens.json" data-line-numbers><code class="lang-json">{
  "Text styles": {
    "Body": {
      "$type": "textStyle",
      "$value": {
        "default": {
          "font": {
            "family": "Neue Haas Grotesk Text Pro",
            "postScriptName": "Neue Haas Grotesk Text Pro",
            "weight": "roman",
            "style": "normal",
            "files": []
          },
<strong>          "fontSize": {
</strong><strong>            "value": 0.875,
</strong><strong>            "unit": "rem"
</strong><strong>          },
</strong>          "color": null,
          "fontFeatures": null,
          "lineHeight": {
            "value": 150,
            "unit": "%"
          },
          "letterSpacing": {
            "value": 0.2,
            "unit": "px"
          },
          "paragraphSpacing": {
            "value": 0,
            "unit": "px"
          },
          "textAlignHorizontal": null,
          "textAlignVertical": null,
          "textDecoration": "none",
          "textIndent": {
            "value": 0,
            "unit": "px"
          },
          "textTransform": "none"
        }
      }
    }
  }
}
</code></pre>

{% endtab %}
{% endtabs %}