feat: support aspect ratio token (#1979)

* feat: add aspect ratio token * test: update snaps * docs: update aspect ratio * docs: update changeset
chakra-ui · Jan 11, 2024 · bee3ec8 · bee3ec8 · vercel · Jan 11, 2024
1 parent 24e9766
commit bee3ec8
Show file tree

Hide file tree

Showing 18 changed files with 163 additions and 18 deletions.
diff --git a/.changeset/polite-buttons-lick.md b/.changeset/polite-buttons-lick.md
@@ -0,0 +1,45 @@
+---
+'@pandacss/token-dictionary': minor
+'@pandacss/preset-panda': minor
+'@pandacss/preset-base': minor
+---
+
+Add support for aspect ratio tokens in the panda config or preset. Aspect ratio tokens are used to define the aspect
+ratio of an element.
+
+```js
+export default defineConfig({
+  // ...
+  theme: {
+    extend: {
+      // add aspect ratio tokens
+      tokens: {
+        aspectRatios: {
+          '1:1': '1',
+          '16:9': '16/9',
+        },
+      },
+    },
+  },
+})
+```
+
+Here's what the default aspect ratio tokens in the base preset looks like:
+
+```json
+{
+  "square": { "value": "1 / 1" },
+  "landscape": { "value": "4 / 3" },
+  "portrait": { "value": "3 / 4" },
+  "wide": { "value": "16 / 9" },
+  "ultrawide": { "value": "18 / 5" },
+  "golden": { "value": "1.618 / 1" }
+}
+```
+
+**Breaking Change**
+
+The built-in token values has been removed from the `aspectRatio` utility to the `@pandacss/preset-base` as a token.
+
+For most users, this change should be a drop-in replacement. However, if you used a custom preset in the config, you
+might need to update it to include the new aspect ratio tokens.
diff --git a/packages/generator/__tests__/generate-prop-types.test.ts b/packages/generator/__tests__/generate-prop-types.test.ts
@@ -17,7 +17,7 @@ describe('generate property types', () => {
       import type { Tokens } from '../tokens/index';
 
       interface PropertyValueTypes {
-      	aspectRatio: \\"auto\\" | \\"square\\" | \\"landscape\\" | \\"portrait\\" | \\"wide\\" | \\"ultrawide\\" | \\"golden\\";
+      	aspectRatio: Tokens[\\"aspectRatios\\"];
       	zIndex: Tokens[\\"zIndex\\"];
       	top: Tokens[\\"spacing\\"];
       	left: Tokens[\\"spacing\\"];
@@ -396,12 +396,15 @@ describe('generate property types', () => {
         | 'visibility'
         | 'wordBreak'
         | 'writingMode'
+
       type WithEscapeHatch<T> = T | \`[\${string}]\`
+
       type FilterVagueString<Key, Value> = Value extends boolean
         ? Value
         : Key extends StrictableProps
           ? Value extends \`\${infer _}\` ? Value : never
           : Value
+
       type PropOrCondition<Key, Value> = ConditionalValue<Value | (string & {})>
 
       type PropertyTypeValue<T extends string> = T extends keyof PropertyTypes
@@ -430,7 +433,7 @@ describe('generate property types', () => {
       import type { Tokens } from '../tokens/index';
 
       interface PropertyValueTypes {
-      	aspectRatio: \\"auto\\" | \\"square\\" | \\"landscape\\" | \\"portrait\\" | \\"wide\\" | \\"ultrawide\\" | \\"golden\\";
+      	aspectRatio: Tokens[\\"aspectRatios\\"];
       	zIndex: Tokens[\\"zIndex\\"];
       	top: Tokens[\\"spacing\\"];
       	left: Tokens[\\"spacing\\"];
@@ -808,12 +811,15 @@ describe('generate property types', () => {
         | 'visibility'
         | 'wordBreak'
         | 'writingMode'
+
       type WithEscapeHatch<T> = T | \`[\${string}]\`
+
       type FilterVagueString<Key, Value> = Value extends boolean
         ? Value
         : Key extends StrictableProps
           ? Value extends \`\${infer _}\` ? Value : never
           : Value
+
       type PropOrCondition<Key, Value> = ConditionalValue<WithEscapeHatch<Value>>
 
       type PropertyTypeValue<T extends string> = T extends keyof PropertyTypes

diff --git a/packages/generator/__tests__/generate-token-dts.test.ts b/packages/generator/__tests__/generate-token-dts.test.ts
diff --git a/packages/generator/__tests__/generate-token-js.test.ts b/packages/generator/__tests__/generate-token-js.test.ts
@@ -13,6 +13,30 @@ test('[dts] should generate package', () => {
   expect(tokenJs(fixtureDefaults)).toMatchInlineSnapshot(
     `
     "const tokens = {
+      \\"aspectRatios.square\\": {
+        \\"value\\": \\"1 / 1\\",
+        \\"variable\\": \\"var(--aspect-ratios-square)\\"
+      },
+      \\"aspectRatios.landscape\\": {
+        \\"value\\": \\"4 / 3\\",
+        \\"variable\\": \\"var(--aspect-ratios-landscape)\\"
+      },
+      \\"aspectRatios.portrait\\": {
+        \\"value\\": \\"3 / 4\\",
+        \\"variable\\": \\"var(--aspect-ratios-portrait)\\"
+      },
+      \\"aspectRatios.wide\\": {
+        \\"value\\": \\"16 / 9\\",
+        \\"variable\\": \\"var(--aspect-ratios-wide)\\"
+      },
+      \\"aspectRatios.ultrawide\\": {
+        \\"value\\": \\"18 / 5\\",
+        \\"variable\\": \\"var(--aspect-ratios-ultrawide)\\"
+      },
+      \\"aspectRatios.golden\\": {
+        \\"value\\": \\"1.618 / 1\\",
+        \\"variable\\": \\"var(--aspect-ratios-golden)\\"
+      },
       \\"borders.none\\": {
         \\"value\\": \\"none\\",
         \\"variable\\": \\"var(--borders-none)\\"

diff --git a/packages/generator/__tests__/generate-token.test.ts b/packages/generator/__tests__/generate-token.test.ts
@@ -16,6 +16,12 @@ describe('generator', () => {
     expect(tokenCss(fixtureDefaults)).toMatchInlineSnapshot(`
       "@layer tokens {
         :where(html) {
+          --aspect-ratios-square: 1 / 1;
+          --aspect-ratios-landscape: 4 / 3;
+          --aspect-ratios-portrait: 3 / 4;
+          --aspect-ratios-wide: 16 / 9;
+          --aspect-ratios-ultrawide: 18 / 5;
+          --aspect-ratios-golden: 1.618 / 1;
           --borders-none: none;
           --easings-default: cubic-bezier(0.4, 0, 0.2, 1);
           --easings-linear: linear;

diff --git a/packages/generator/src/artifacts/types/prop-types.ts b/packages/generator/src/artifacts/types/prop-types.ts
@@ -118,12 +118,15 @@ export function generatePropTypes(ctx: Context) {
     | 'visibility'
     | 'wordBreak'
     | 'writingMode'
+  
   type WithEscapeHatch<T> = T | \`[\${string}]\`
+  
   type FilterVagueString<Key, Value> = Value extends boolean
     ? Value
     : Key extends StrictableProps
       ? Value extends \`\${infer _}\` ? Value : never
       : Value
+  
   type PropOrCondition<Key, Value> = ${match(ctx.config)
     .with(
       { strictTokens: true, strictPropertyValues: true },

diff --git a/packages/generator/src/artifacts/types/token-types.ts b/packages/generator/src/artifacts/types/token-types.ts
@@ -4,6 +4,7 @@ import { outdent } from 'outdent'
 import pluralize from 'pluralize'
 
 const categories = [
+  'aspectRatios',
   'zIndex',
   'opacity',
   'colors',

diff --git a/packages/preset-base/src/utilities/layout.ts b/packages/preset-base/src/utilities/layout.ts
@@ -3,15 +3,7 @@ import type { UtilityConfig } from '@pandacss/types'
 export const layout: UtilityConfig = {
   aspectRatio: {
     className: 'aspect',
-    values: {
-      auto: 'auto',
-      square: '1 / 1',
-      landscape: '4 / 3',
-      portrait: '3 / 4',
-      wide: '16 / 9',
-      ultrawide: '18 / 5',
-      golden: '1.618 / 1',
-    },
+    values: 'aspectRatios',
   },
   boxDecorationBreak: {
     className: 'decoration',

diff --git a/packages/preset-panda/src/aspect-ratios.ts b/packages/preset-panda/src/aspect-ratios.ts
@@ -0,0 +1,8 @@
+export const aspectRatios = {
+  square: { value: '1 / 1' },
+  landscape: { value: '4 / 3' },
+  portrait: { value: '3 / 4' },
+  wide: { value: '16 / 9' },
+  ultrawide: { value: '18 / 5' },
+  golden: { value: '1.618 / 1' },
+}
diff --git a/packages/preset-panda/src/tokens.ts b/packages/preset-panda/src/tokens.ts
@@ -1,7 +1,8 @@
 import type { Tokens } from '@pandacss/types'
+import { aspectRatios } from './aspect-ratios'
+import { borders } from './borders'
 import { colors } from './colors'
 import { animations } from './keyframes'
-import { borders } from './borders'
 import { shadows } from './shadows'
 import { sizes } from './sizes'
 import { spacing } from './spacing'
@@ -10,6 +11,7 @@ import { fonts, fontSizes, fontWeights, letterSpacings, lineHeights } from './ty
 const defineTokens = <T extends Tokens>(v: T) => v
 
 export const tokens = defineTokens({
+  aspectRatios,
   borders,
   easings: {
     default: { value: 'cubic-bezier(0.4, 0, 0.2, 1)' },

diff --git a/packages/studio/styled-system/tokens/index.mjs b/packages/studio/styled-system/tokens/index.mjs
@@ -1,4 +1,28 @@
 const tokens = {
+  "aspectRatios.square": {
+    "value": "1 / 1",
+    "variable": "var(--aspect-ratios-square)"
+  },
+  "aspectRatios.landscape": {
+    "value": "4 / 3",
+    "variable": "var(--aspect-ratios-landscape)"
+  },
+  "aspectRatios.portrait": {
+    "value": "3 / 4",
+    "variable": "var(--aspect-ratios-portrait)"
+  },
+  "aspectRatios.wide": {
+    "value": "16 / 9",
+    "variable": "var(--aspect-ratios-wide)"
+  },
+  "aspectRatios.ultrawide": {
+    "value": "18 / 5",
+    "variable": "var(--aspect-ratios-ultrawide)"
+  },
+  "aspectRatios.golden": {
+    "value": "1.618 / 1",
+    "variable": "var(--aspect-ratios-golden)"
+  },
   "borders.none": {
     "value": "none",
     "variable": "var(--borders-none)"

diff --git a/packages/studio/styled-system/tokens/tokens.d.ts b/packages/studio/styled-system/tokens/tokens.d.ts
diff --git a/packages/studio/styled-system/types/prop-type.d.ts b/packages/studio/styled-system/types/prop-type.d.ts
@@ -4,7 +4,7 @@ import type { CssProperties } from './system-types';
 import type { Tokens } from '../tokens/index';
 
 interface PropertyValueTypes {
-	aspectRatio: "auto" | "square" | "landscape" | "portrait" | "wide" | "ultrawide" | "golden";
+	aspectRatio: Tokens["aspectRatios"];
 	zIndex: Tokens["zIndex"];
 	top: Tokens["spacing"];
 	left: Tokens["spacing"];
@@ -383,12 +383,15 @@ type StrictableProps =
   | 'visibility'
   | 'wordBreak'
   | 'writingMode'
+
 type WithEscapeHatch<T> = T | `[${string}]`
+
 type FilterVagueString<Key, Value> = Value extends boolean
   ? Value
   : Key extends StrictableProps
     ? Value extends `${infer _}` ? Value : never
     : Value
+
 type PropOrCondition<Key, Value> = ConditionalValue<Value | (string & {})>
 
 type PropertyTypeValue<T extends string> = T extends keyof PropertyTypes

diff --git a/packages/token-dictionary/__tests__/tokens.test.ts b/packages/token-dictionary/__tests__/tokens.test.ts
@@ -1522,6 +1522,14 @@ test('should work with default fixture', () => {
 
   expect(formats.getFlattenedValues(dictionary)).toMatchInlineSnapshot(`
     Map {
+      "aspectRatios" => Map {
+        "square" => "var(--aspect-ratios-square)",
+        "landscape" => "var(--aspect-ratios-landscape)",
+        "portrait" => "var(--aspect-ratios-portrait)",
+        "wide" => "var(--aspect-ratios-wide)",
+        "ultrawide" => "var(--aspect-ratios-ultrawide)",
+        "golden" => "var(--aspect-ratios-golden)",
+      },
       "borders" => Map {
         "none" => "var(--borders-none)",
       },

diff --git a/packages/token-dictionary/src/token.ts b/packages/token-dictionary/src/token.ts
@@ -235,4 +235,5 @@ const TOKEN_TYPES = {
   borders: 'border',
   components: 'cti',
   assets: 'asset',
+  aspectRatios: 'aspectRatio',
 }
diff --git a/packages/types/src/tokens.ts b/packages/types/src/tokens.ts
@@ -89,6 +89,7 @@ export interface TokenDataTypes {
   gradients: string | Gradient
   assets: string | Asset
   borderWidths: string
+  aspectRatios: string
 }
 
 export type Tokens = {

diff --git a/website/pages/docs/theming/tokens.md b/website/pages/docs/theming/tokens.md
@@ -566,6 +566,21 @@ const theme = {
 
 > Animation tokens are typically used in `animation` property.
 
+### Aspect Ratios
+
+Aspect ratio tokens represent the aspect ratio of an element. Its value is defined as a string.
+
+```jsx
+const theme = {
+  tokens: {
+    aspectRatios: {
+      '1:1': { value: '1 / 1' },
+      '16:9': { value: '16 / 9' }
+    }
+  }
+}
+```
+
 ## Token Helpers
 
 To help defining tokens in a type-safe way, you can use the tokens [Config Functions](/docs/customization/config-functions#token-creators).
diff --git a/website/pages/docs/utilities/layout.md b/website/pages/docs/utilities/layout.md
@@ -11,7 +11,7 @@ Panda provides style properties for styling layout of an element
 
 Use the `aspectRatio` utilities to set the desired aspect ratio of an element.
 
-Values can be `square`, `portrait`, `landscape`, `wide`, `ultrawide`, `golden` or a number.
+Values can reference the `aspectRatios` token category.
 
 ```jsx
 <div className={css({ aspectRatio: 'square' })} />