@codecademy/styleguide 79.0.1-alpha.2b3284.0 → 79.0.1-alpha.d8b528.0

package/src/lib/Foundations/shared/elements.tsx

@@ -2,22 +2,32 @@ import { Anchor, Box } from '@codecademy/gamut';
 import {
   Background,
   coreSwatches,
+  css,
   lxStudioColors,
   theme,
   trueColors,
 } from '@codecademy/gamut-styles';
 // eslint-disable-next-line gamut/import-paths
 import * as ALL_PROPS from '@codecademy/gamut-styles/src/variance/config';
+import { useTheme } from '@emotion/react';
+import styled from '@emotion/styled';
 import kebabCase from 'lodash/kebabCase';
 
 import { Code, ColorScale, LinkTo, TokenTable } from '~styleguide/blocks';
 
 import { applyCorrectNotation } from './applyCorrectNotation';
 
+const AnchorCode = styled(Code)(
+  css({
+    textDecoration: 'underline',
+    mx: 4,
+  })
+);
+
 export const PROP_COLUMN = {
   key: 'key',
   name: 'Prop',
-  size: 'md',
+  size: 'lg',
   render: ({ id }: any) => <Code>{id}</Code>,
 };
 
@@ -403,26 +413,61 @@ export const DarkModeTable = () => (
 );
 /* eslint-disable gamut/import-paths */
 
+const PropertiesRenderer = ({
+  property,
+  properties,
+  resolveProperty,
+}: {
+  property: string | { physical: string; logical: string };
+  properties?: string[] | { physical: string[]; logical: string[] };
+  resolveProperty?: (useLogicalProperties: boolean) => 'logical' | 'physical';
+}) => {
+  const currentTheme = useTheme() as { useLogicalProperties?: boolean };
+  const useLogicalProperties = currentTheme?.useLogicalProperties ?? true;
+
+  const mode = resolveProperty
+    ? resolveProperty(useLogicalProperties)
+    : 'physical';
+
+  const resolvedProperty =
+    typeof property === 'string' ? property : property[mode];
+
+  let resolvedProperties: string[];
+  if (!properties) {
+    resolvedProperties = [resolvedProperty];
+  } else if (Array.isArray(properties)) {
+    resolvedProperties = properties;
+  } else {
+    resolvedProperties = properties[mode];
+  }
+
+  return (
+    <>
+      {resolvedProperties.map((prop) => (
+        <Anchor
+          href={`https://developer.mozilla.org/en-US/docs/Web/CSS/${kebabCase(
+            prop
+          )}`}
+          key={prop}
+          rel=""
+          target="_blank"
+        >
+          <AnchorCode>{kebabCase(prop)}</AnchorCode>
+        </Anchor>
+      ))}
+    </>
+  );
+};
+
 const PROPERTIES_COLUMN = {
   key: 'properties',
   name: 'Properties',
   size: 'xl',
-  render: ({
-    property,
-    properties = [property],
-  }: {
-    property: string;
-    properties: string[];
-  }) =>
-    properties.map((property) => (
-      <Anchor
-        href={`https://developer.mozilla.org/en-US/docs/Web/CSS/${property}`}
-        rel=""
-        target="_blank"
-      >
-        <Code key={property}>{kebabCase(property)}</Code>
-      </Anchor>
-    )),
+  render: (props: {
+    property: string | { physical: string; logical: string };
+    properties?: string[] | { physical: string[]; logical: string[] };
+    resolveProperty?: (useLogicalProperties: boolean) => 'logical' | 'physical';
+  }) => <PropertiesRenderer {...props} />,
 };
 
 const SCALE_COLUMN = {
@@ -430,7 +475,7 @@ const SCALE_COLUMN = {
   name: 'Scale',
   size: 'lg',
   render: ({ scale }: { scale: string }) => (
-    <LinkTo id={`foundations-theme--${kebabCase(scale)}`}>{scale}</LinkTo>
+    <LinkTo id="Foundations/Theme/Core Theme">{scale}</LinkTo>
   ),
 };
 
@@ -438,7 +483,12 @@ const TRANSFORM_COLUMN = {
   key: 'transform',
   name: 'Transform',
   size: 'fill',
-  render: ({ transform }: any) => transform && <Code>{transform?.name}</Code>,
+  render: ({ transform, resolveProperty }: any) => (
+    <>
+      {transform && <Code>{transform?.name}</Code>}
+      {resolveProperty && <Code>{resolveProperty?.name}</Code>}
+    </>
+  ),
 };
 
 export const defaultColumns = [

package/src/lib/Meta/About.mdx

@@ -13,6 +13,7 @@ import { parameters as deepControlsParameters } from './Deep Controls Add-On.mdx
 import { parameters as eslintRulesParameters } from './ESLint rules.mdx';
 import { parameters as faqsParameters } from './FAQs.mdx';
 import { parameters as installationParameters } from './Installation.mdx';
+import { parameters as logicalPhysicalParameters } from './Logical and physical CSS properties.mdx';
 import { parameters as storiesParameters } from './Stories.mdx';
 import { parameters as usageGuideParameters } from './Usage Guide.mdx';
 
@@ -34,9 +35,10 @@ export const parameters = {
     deepControlsParameters,
     eslintRulesParameters,
     faqsParameters,
+    installationParameters,
+    logicalPhysicalParameters,
     storiesParameters,
     brandParameters,
-    installationParameters,
     usageGuideParameters,
   ])}
 />

package/src/lib/Meta/Logical and physical CSS properties.mdx

@@ -0,0 +1,123 @@
+import { Meta } from '@storybook/blocks';
+
+import {
+  AboutHeader,
+  Callout,
+  Code,
+  ImageWrapper,
+  TokenTable,
+} from '~styleguide/blocks';
+
+export const parameters = {
+  id: 'Meta/Logical and physical CSS properties',
+  title: 'Logical and physical CSS properties',
+  subtitle:
+    'Understanding CSS logical and physical properties and how Gamut supports both modes.',
+  status: 'static',
+};
+
+<Meta title="Meta/Logical and physical CSS properties" />
+
+<AboutHeader {...parameters} />
+
+## What are CSS logical properties?
+
+CSS logical properties are a modern approach to styling that adapts to the writing mode and text direction of your content, rather than being tied to physical screen directions. More information can be found on[MDN: CSS Logical Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values)
+
+### Physical Properties (Traditional)
+
+Physical properties reference the physical dimensions of the viewport. For example:
+
+- `margin-left`, `margin-right`, `margin-top`, `margin-bottom`
+- `padding-left`, `padding-right`, `padding-top`, `padding-bottom`
+
+These work well for left-to-right (LTR) languages but require manual overrides for right-to-left (RTL) languages like Arabic or Hebrew.
+
+### Logical Properties (Modern)
+
+Logical properties reference the flow of content:
+
+- **Inline axis** (text direction): `margin-inline-start`, `margin-inline-end`
+- **Block axis** (reading direction): `margin-block-start`, `margin-block-end`
+
+## Using `useLogicalProperties` in Gamut
+
+Gamut supports both physical and logical CSS properties through the `useLogicalProperties` prop on `GamutProvider`. This allows you to choose which mode your application uses. By default, `useLogicalProperties` is set to `true`, meaning Gamut will use logical CSS properties. If you want to use physical CSS properties, you have to set `useLogicalProperties` to `false`.
+
+### Affected Props
+
+Here are some examples of how physical and logical properties are affected by the `useLogicalProperties` prop:
+
+<TokenTable
+  idKey="prop"
+  columns={[
+    {
+      key: 'prop',
+      name: 'Prop',
+      size: 'sm',
+      render: ({ prop }) => <Code>{prop}</Code>,
+    },
+    {
+      key: 'physical',
+      name: 'Physical',
+      size: 'xl',
+      render: ({ physical }) =>
+        physical.map((p) => (
+          <>
+            <Code key={p}>{p}</Code>{' '}
+          </>
+        )),
+    },
+    {
+      key: 'logical',
+      name: 'Logical',
+      size: 'xl',
+      render: ({ logical }) =>
+        logical.map((l) => (
+          <>
+            <Code key={l}>{l}</Code>{' '}
+          </>
+        )),
+    },
+  ]}
+  rows={[
+    {
+      prop: 'mx',
+      physical: ['margin-left', 'margin-right'],
+      logical: ['margin-inline-start', 'margin-inline-end'],
+    },
+    { prop: 'mt', physical: ['margin-top'], logical: ['margin-block-start'] },
+    {
+      prop: 'py',
+      physical: ['padding-top', 'padding-bottom'],
+      logical: ['padding-block-start', 'padding-block-end'],
+    },
+    {
+      prop: 'pb',
+      physical: ['padding-bottom'],
+      logical: ['padding-block-end'],
+    },
+  ]}
+/>
+
+<Callout
+  text={
+    <>
+      Props like <code>m</code> and <code>p</code> (which set all four sides at
+      once) are not affected by this setting, as the CSS <code>margin</code> and{' '}
+      <code>padding</code> shorthands work identically in both modes.
+    </>
+  }
+/>
+
+## Previewing in Storybook
+
+You can toggle between logical and physical properties in Storybook using the **LogicalProps** toolbar button:
+
+<ImageWrapper
+  src="./meta/toolbar.png"
+  alt="The Storybook toolbar with the LogicalProps toggle highlighted."
+  height="auto"
+/>
+
+This allows you to preview how components render with either property mode without changing any code.

package/src/lib/Meta/Usage Guide.mdx

@@ -39,7 +39,8 @@ On each page is a toolbar located on the top:
 1. Grid (the 2x2 collection of squares) - applies a grid to the preview
 2. Color mode selector (the circle icon) - toggles between light and dark mode for rendered code examples
 3. Theme switcher (the paintbrush icon) - switches between different design system themes (Core, Admin, LX Studio, Percipio)
-4. Outline (dotted square) - applies outlines to elements in the rendered code examples
+4. LogicalProps (the two arrows icon) - toggles between physical and logical CSS properties
+5. Outline (dotted square) - applies outlines to elements in the rendered code examples
 
 ### Theme Switcher
 
@@ -58,6 +59,10 @@ Available themes:
 
 The theme switcher works in combination with the color mode selector, so you can test both light and dark variants of each theme.
 
+### LogicalProps
+
+The LogicalProps button (two arrows icon) provides a menu to select between Logical and Physical CSS properties.
+
 ### Showing code
 
 On the bottom right of each canvas (a rendered code example) is a button to show its code:

package/src/lib/Molecules/Popover/Popover.stories.tsx

@@ -8,7 +8,7 @@ import {
 } from '@codecademy/gamut';
 import * as patterns from '@codecademy/gamut-patterns';
 import type { Meta, StoryObj } from '@storybook/react';
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useRef, useState } from 'react';
 
 const meta: Meta<typeof Popover> = {
   component: Popover,
@@ -27,91 +27,10 @@ type Story = StoryObj<typeof Popover>;
 
 type PopoverExampleProps = PopoverProps & Pick<FlexBoxProps, 'p'>;
 
-const POPOVER_HEIGHT_ESTIMATE = 200; // Estimate for flip calculation
-const VIEWPORT_PADDING = 16; // Padding from viewport edge
-
-const PopoverExample = ({
-  p = 16,
-  position: preferredPosition = 'below',
-  ...rest
-}: PopoverExampleProps) => {
+const PopoverExample = ({ p = 16, ...rest }: PopoverExampleProps) => {
   const [open, setOpen] = useState(false);
-  const [computedPosition, setComputedPosition] = useState<
-    'above' | 'below' | 'center'
-  >(preferredPosition === 'center' ? 'center' : preferredPosition);
-  const [availableHeight, setAvailableHeight] = useState<number | undefined>(
-    undefined
-  );
   const activeElRef = useRef<HTMLDivElement>(null);
-  const popoverRef = useRef<HTMLDivElement>(null);
-  const [popoverHeight, setPopoverHeight] = useState(POPOVER_HEIGHT_ESTIMATE);
-
-  const calculatePosition = useCallback(() => {
-    const target = activeElRef.current;
-    if (!target || preferredPosition === 'center') return;
-
-    const targetRect = target.getBoundingClientRect();
-    const viewportHeight = window.innerHeight;
-
-    const spaceBelow = viewportHeight - targetRect.bottom - VIEWPORT_PADDING;
-    const spaceAbove = targetRect.top - VIEWPORT_PADDING;
-
-    // Use measured height if available, otherwise estimate
-    const heightToFit = popoverHeight;
-
-    let newPosition: 'above' | 'below' =
-      preferredPosition === 'above' ? 'above' : 'below';
-
-    if (preferredPosition === 'below') {
-      // Prefer below, but flip to above if not enough space below and more space above
-      if (spaceBelow < heightToFit && spaceAbove > spaceBelow) {
-        newPosition = 'above';
-      } else {
-        newPosition = 'below';
-      }
-    } else if (preferredPosition === 'above') {
-      // Prefer above, but flip to below if not enough space above and more space below
-      if (spaceAbove < heightToFit && spaceBelow > spaceAbove) {
-        newPosition = 'below';
-      } else {
-        newPosition = 'above';
-      }
-    }
-
-    setComputedPosition(newPosition);
-
-    // Set max height based on the available space in the computed direction
-    const maxAvailableHeight = newPosition === 'below' ? spaceBelow : spaceAbove;
-    setAvailableHeight(Math.max(maxAvailableHeight, 100)); // Minimum 100px
-  }, [preferredPosition, popoverHeight]);
-
-  // Measure popover height when it opens
-  useEffect(() => {
-    if (open && popoverRef.current) {
-      const { height } = popoverRef.current.getBoundingClientRect();
-      if (height > 0) {
-        setPopoverHeight(height);
-      }
-    }
-  }, [open]);
-
-  // Recalculate position on open, scroll, or resize
-  useEffect(() => {
-    if (!open) return;
-
-    calculatePosition();
-
-    window.addEventListener('scroll', calculatePosition, true);
-    window.addEventListener('resize', calculatePosition);
-
-    return () => {
-      window.removeEventListener('scroll', calculatePosition, true);
-      window.removeEventListener('resize', calculatePosition);
-    };
-  }, [open, calculatePosition]);
-
   const toggleOpen = () => setOpen(!open);
-
   return (
     <>
       <Box ref={activeElRef} width="fit-content">
@@ -121,53 +40,11 @@ const PopoverExample = ({
         <Popover
           {...(rest as any)}
           isOpen={open}
-          popoverContainerRef={popoverRef}
-          position={computedPosition}
           targetRef={activeElRef}
           onRequestClose={() => setOpen(false)}
         >
-          {/*
-            Apply maxHeight and overflow to the content wrapper.
-            This makes the popover contents scrollable when they exceed
-            the available viewport space.
-          */}
-          <FlexBox
-            alignItems="flex-start"
-            flexDirection="column"
-            p={p}
-            maxHeight={availableHeight ? `${availableHeight}px` as any : undefined}
-            overflowY="auto"
-          >
-            <Box mb={8}>
-              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do
-              eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
-              enim ad minim veniam, quis nostrud exercitation ullamco laboris
-              nisi ut aliquip ex ea commodo consequat.
-            </Box>
-            <Box mb={8}>
-              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do
-              eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
-              enim ad minim veniam, quis nostrud exercitation ullamco laboris
-              nisi ut aliquip ex ea commodo consequat.
-            </Box>
-            <Box mb={8}>
-              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do
-              eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
-              enim ad minim veniam, quis nostrud exercitation ullamco laboris
-              nisi ut aliquip ex ea commodo consequat.
-            </Box>
-            <Box mb={8}>
-              Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do
-              eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
-              enim ad minim veniam, quis nostrud exercitation ullamco laboris
-              nisi ut aliquip ex ea commodo consequat.
-            </Box>
-            <Box mb={8} opacity={0.7}>
-              Position: {computedPosition}
-              {computedPosition !== preferredPosition && ' (flipped!)'}
-              {' | '}
-              Max height: {availableHeight ? `${Math.round(availableHeight)}px` : 'auto'}
-            </Box>
+          <FlexBox alignItems="flex-start" flexDirection="column" p={p}>
+            <Box mb={8}>Hooray!</Box>
             <FillButton size="small" onClick={() => setOpen(false)}>
               Close Popover
             </FillButton>

package/src/lib/Foundations/System/Props.mdx

@@ -1,230 +0,0 @@
-import { Meta } from '@storybook/blocks';
-
-import { AboutHeader, TokenTable } from '~styleguide/blocks';
-
-import { defaultColumns, getPropRows } from '../shared/elements';
-
-export const parameters = {
-  title: 'Props',
-  subtitle:
-    'Reusable CSS-in-JS props with predictable behaviors and a consistent API for responsive CSS.',
-  source: {
-    repo: 'gamut-styles',
-    githubLink:
-      'https://github.com/Codecademy/gamut/blob/af5be6e39cccca5d5d8a1f811c77a7a0b618c914/packages/gamut-styles/src/variance/config.ts#L11',
-  },
-};
-
-<Meta title="Foundations/System/Props" />
-
-<AboutHeader {...parameters} />
-
-We provide a set of out of style functions out of the box through `@codecademy/gamut-styles` that are standardized throughout all of our components. These props are strongly typed and can be included as necessary on any styled component.
-
-System props have a few facets that are important to note:
-
-- They can some times represent multiple properties.
-- They may be restricted to specific token scales but will always have access to global css values like `initial` and `none`.
-- They may have a function that transforms the given value into a standardized value (e.g. `width={.5}` => `width: 50%`)
-
-We've grouped these into a few main groups that affect simliar behaviors: `layout`, `space`, `color`, `border`, `background`, `typography`, `positioning`, `grid`, `flex`, `shadow`.
-
-You may import these groups directly from `gamut-styles`.
-
-```tsx
-import { variance } from '@codecademy/variance';
-import { system } from '@codecademy/gamut-styles';
-
-const Box = styled.div(variance.compose(system.layout, system.positioning));
-
-<Box position="absolute" width="50px" height="50px" />;
-```
-
-Each system prop has 3 important features:
-
-- `properties`: Any number of CSS Properties this prop is responsible for.
-- `scale`: A set of values that determines valid inputs for each prop (e.g. a scale of `colors` will restrict to only theme colors). These are generally aliases for more verbose or opaque css properties allowing you to specify a human readable name in your props. If a prop doesn't have a scale that means it accepts all valid CSSType values as props, however if it does have a scale it will only accept global values and keys of the provided scale.
-- `transform`: A function that changes the prop / scale value prior to adding it to the stylehseet. This allows us to add / change units for properties like `width` and `height`. Or ensure extra defaults or fallbacks are added dynamically.
-
-<br />
-
-## Layout
-
-Props for handling dimensions and other layout specific properties.
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const Box = styled.div(system.layout);
-
-<Box display="flex" width="50%" height="300px" verticalAlign="middle" />;
-```
-
-<TokenTable rows={getPropRows('layout')} columns={defaultColumns} />
-
-## Space
-
-Props for maintaining specific vertical and horizontal rhythms
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const Spacer = styled.div(system.space);
-
-<Spacer p={8} my={[16, 24, 32]} />;
-```
-
-<TokenTable rows={getPropRows('space')} columns={defaultColumns} />
-
-## Typography
-
-Props for text manipulation
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const Text = styled.p(system.typography);
-
-<Text fontSize={16} fontFamily="accent" textTransform="uppercase" />;
-```
-
-<TokenTable rows={getPropRows('typography')} columns={defaultColumns} />
-
-## Color
-
-Specific color properties
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const Background = styled.div(system.color);
-
-<Background bg="navy" textColor="gray-100" borderColor="blue" />;
-```
-
-<TokenTable rows={getPropRows('color')} columns={defaultColumns} />
-
-## Border
-
-Border styles
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const Box = styled.div(system.border);
-
-<Box
-  border={1}
-  borderLeft="none"
-  borderRightStyle="dotted"
-  borderRadius="md"
-/>;
-```
-
-<TokenTable rows={getPropRows('border')} columns={defaultColumns} />
-
-## Flex
-
-Flex specific properties
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const FlexBox = styled.div(system.flex);
-
-<FlexBox flex={1} justifyContent="center" alignItems="flex-start" />;
-```
-
-<TokenTable rows={getPropRows('flex')} columns={defaultColumns} />
-
-## Grid
-
-Grid specific properties
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const GridBox = styled.div(system.grid);
-
-<GridBox gridTemplateColumns="max-content 1fr max-content" columnGap={32} />;
-```
-
-<TokenTable rows={getPropRows('grid')} columns={defaultColumns} />
-
-## Background
-
-Props for background manipulation (sizing / repitition / images), for background color see `colors`.
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-import myBg from './myBg.png';
-
-const Box = styled.div(system.background);
-
-<Box background={`url(${myBg}`} backgroundSize="cover" />;
-```
-
-<TokenTable rows={getPropRows('background')} columns={defaultColumns} />
-
-## Positioning
-
-Props that affect stacking and position contexts. Like `top`, `position` and `opacity`.
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const Box = styled.div(system.positioning);
-
-<Box position="absolute" zIndex={2} top="0" left="0" />;
-```
-
-<TokenTable rows={getPropRows('positioning')} columns={defaultColumns} />
-
-## Shadow
-
-Props for box and text shadows.
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const Box = styled.div(system.shadow);
-
-<Box
-  boxShadow="0 0 4px rgba(0, 0, 0, .15)"
-  textShadow="0 0 4px rgba(0, 0, 0, .15)"
-/>;
-```
-
-<TokenTable rows={getPropRows('shadows')} columns={defaultColumns} />
-
-## List
-
-Props for adjusting list styles when rendering a component as a `ul` or `ol`
-
-```tsx
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const Box = styled.div(system.list);
-
-<Box
-  as="ul"
-  listStyleType="square"
-  listStylePosition="inside"
-  listStyleImage="none"
->
-  <Box as="li">a list item</Box>
-</Box>;
-```
-
-<TokenTable rows={getPropRows('list')} columns={defaultColumns} />