@elliemae/ds-system 3.33.0-next.0 → 3.33.0-next.2

package/dist/cjs/styled/Documentation.md

@@ -0,0 +1,252 @@
+### Internal Workings of the Styled-Component Wrapper
+
+This document delves into the internal mechanics of our custom styled-component wrapper, providing insights for developers who need to understand or extend its functionality.
+
+#### Overview
+The wrapper is designed to extend the standard functionality of styled-components with additional features like automatic theme coercion, design system integration, and automatic attribute generation. It acts as a higher-order component (HOC) that wraps around the base styled component.
+
+#### Understanding Tagged Template Literals
+In standard styled-components usage, styled components are often defined using tagged template literals, a feature of ES6. For example:
+
+```typescript
+const StyledButton = styled.button`
+  margin: ${({ theme }) => theme.space.xs};
+`;
+```
+
+This syntax is concise and readable, especially for defining component styles that directly leverage props and themes.
+
+But, for the purpose of this document, you should understand the real way this gets "transpiled" to:
+
+```typescript
+styled('button')(['margin: ', ';\n'], ({theme}) => theme.space.xs);
+```
+
+So, `styled` is a function that takes a tag (in this case, `'button'`) and returns a function that takes any number of arguments. The first argument is an array of strings (the constant parts of the template literal), and the rest are the interpolated values (the dynamic parts of the template literal). Each interpolated value will be inserted into the array of strings at the corresponding index.
+
+This is just for the most-used-case on our library though. Styled components also accept object instead of tagged template literals, and we have to handle that as well. So keep that in mind as well.
+
+#### The idea of the Wrapper
+
+The wrapper is designed to also receive as a parameter an options object, along with the tag. So the signature of the wrapper is:
+
+```typescript
+const OurStyled = (tag: Tag, options: {name: string, slot: string}) => ReturnType<styled('tag')>
+```
+
+These name and slot properties will be used for theming the styled component, for applying style and variant overrides from the design system, calculate data-testids, data-dimsum-slot and other attributes as well, ref-merging, etc.
+
+#### Let's see the code
+
+```typescript
+checkNamingConvention(componentName, componentSlot);
+```
+
+This function checks if the `name` and `slot` properties adhere to our project's naming conventions. If they don't, it triggers a warning.
+
+The correct format for componentName is `DSComponentName`, and for componentSlot is `component-slot`. This is important since other functionalities rely on these properties being correctly formatted.
+
+Now, let's look at the overall body of the function
+
+```typescript
+const baseStyledResolver = baseStyled(tag) as unknown as ThemedStyledFunction<C, Theme, {}, keyof any>;
+
+const dsStyledResolver: ThemedStyledFunctionBase<C, Theme> = (styleArg, ...expressions) => {
+    ... some code that we will see later ...
+};
+
+// Here we use arrow functions to preserve the `this` context
+const styledAttributes = {
+attrs: ((...args) => {
+    baseStyledResolver.attrs(...args);
+    return dsStyledResolver;
+}) as (typeof baseStyledResolver)['attrs'],
+withConfig: ((...args) => {
+    baseStyledResolver.withConfig(...args);
+    return dsStyledResolver;
+}) as (typeof baseStyledResolver)['withConfig'],
+};
+
+return Object.assign(dsStyledResolver, styledAttributes);
+
+```
+
+It looks scary. But let's break it down.
+
+1. We create a base styled resolver using the `baseStyled` function. This is just calling the ORIGINAL `styled` function from `styled-components` (we just changed its name when importing it).
+Ultimately, this is the function that will be called when we use our styled component, since we are just building a wrapper of it.
+
+2. We create a new resolver, `dsStyledResolver`, that will be the one that will be returned by our wrapper. It has to receive as a first argument the styleArg, which is the style object or string that we pass to the styled component. The rest of the arguments are the interpolated values of the tagged template literal.
+This function will do a lot of magic, but it will ultimately call the `baseStyledResolver` with the correct arguments.
+
+3. We create an object with two methods, `attrs` and `withConfig`, that will be used to augment the styled component. These methods are just calling the original methods of the `baseStyledResolver`, and then returning the `dsStyledResolver` itself. This is just to make sure that the styled component is augmented with the correct methods.
+
+4. We return an object that is the `dsStyledResolver` with the two methods we created. This is the final object that will be returned by our wrapper.
+
+This is just a basic wrapper flow, with an extra step for the `attrs` and `withConfig` function. The `dsStyledResolver` is the one that will be used to create the styled component, and it will have all the magic we need to make it work with our design system.
+
+Now let's see the `dsStyledResolver` function:
+
+```typescript
+const expressionsWithDsStyledComponentId = dsStyledComponentTransform(expressions);
+```
+
+Well, this function is needed for something we do later in the code, but the basic idea is to support this syntax:
+
+```typescript
+const StyledChat = styled('div')`
+    ${StyledChatBubble} {
+        margin: 0;
+    }
+`;
+```
+
+Now that you understand how the tagged template literals work, you can see that we are interpolating a styled component inside another styled component. This is a common pattern in our codebase, and we need to support it.
+
+Our styled-component, will have a `dsStyledComponentId` added to them, so we can reference them on this transformation.
+
+The `dsStyledComponentTransform` function will transform the styled component into its `dsStyledComponentId` so we can use it on the interpolation.
+
+So basically it will transform `StyledChatBubble`
+
+```typescript
+`.${StyledChatBubble.dsStyledComponentId}`
+```
+
+Notice the `.` before the interpolation. This is because we are interpolating a class name, and we need to add the `.` to make it a valid CSS selector.
+
+```typescript
+    const [styleArgWithMagic, expressionsWithMagic] = magicCssTransform(styleArg, expressionsWithDsStyledComponentId);
+```
+
+This transformation allows our styled components to be MAGICAL. Meaning, we support things like this:
+
+```typescript
+const StyledButton = styled('button')`
+    color: neutral-100;
+`;
+```
+
+Doing this is not so simple, but I will try to explain it in a simple way.
+
+First we need to do a regex search to locate something that we can replace with a theme getter (for now we just support colors, but we can extend it to other things).
+
+Then we need to replace that token with the corresponding value from the theme, using a function, so it's the same as this:
+
+```typescript
+const StyledButton = styled('button')`
+    color: ${({theme}) => theme.colors.neutral[100]};
+`;
+```
+
+Now, let's analyze the styleArg vs expressions thing.
+
+Before this transformation, styleArg was: `color: neutral 100;\n`, and no expressions.
+
+After this transformation, styleArg is `["color: ", ";\n"]` and expressions is `[({theme}) => theme.colors.neutral[100]]`.
+
+So, every time we find a token, we split the styleArg in two, and a function is added to the expressions array.
+
+Let's see the next part of the code:
+
+```typescript
+const expressionsWithThemeCoerced = coerceWithDefaultTheme(expressionsWithMagic);
+```
+
+This transformation just adds a default theme in case no theme was provided on the application. So basically we just replace every function on the expressions array with a new function with the theme coerced.
+
+```
+expresions = [f1, f2, f3]
+
+-->
+
+expressions = [({theme,...rest}) => f1({...rest, theme: theme ?? defaultTheme}), ...]
+```
+
+
+Let's look at the next important part
+
+```typescript
+if (componentName && componentSlot) {
+    expressionsWithThemeCoerced.push(genStyleOverridesExpression(componentName, componentSlot));
+}
+
+if (componentName && componentSlot === 'root') {
+    expressionsWithThemeCoerced.push(genVariantOverridesExpression(componentName));
+}
+
+const numOfExpressionsAdded = expressionsWithThemeCoerced.length - expressionsWithMagic.length;
+
+const fixedStyleArg = fixStyleArg(styleArgWithMagic, numOfExpressionsAdded);
+```
+
+This is where we add both style and variant overrides to the styled component. Here we access the theme object in search of the corresponding variant and style overrides, and we push them into the expressions array.
+
+Notice that we are adding the expressions at the end of the array, so they will be the last ones to be evaluated, therefore they will override any previous styles.
+
+It's also important to note that we need to fix the styleArg after adding the expressions, since we added new expressions, and we need to adjust the styleArg to match the new expressions array.
+
+
+In the next part, we just generate some autocalculated values, like display name, data-testids, classNames, etc. And then, we just add them one by one by using the `attrs` function
+
+```typescript
+const [displayName, attributes] = generateAutoCalculated(options);
+
+const baseStyledResolverWithAttributes = attributes.reduce<typeof baseStyledResolver>(
+    (curStyledResolver, attributeFunc) => curStyledResolver.attrs(attributeFunc),
+    baseStyledResolver,
+);
+```
+
+Notice that we are using the `baseStyledResolver` here!!! We are adding the attributes to the original styled.
+Now, we will call this styled with the styleArg and expression that we calculated before, and we will return the styled component.
+
+```typescript
+const Component = baseStyledResolverWithAttributes(fixedStyleArg, ...expressionsWithThemeCoerced);
+```
+
+So, wrapper ONLY augments the styleArg and expressions, and then calls the original styled function with the augmented arguments.
+
+There is an extra piece of logic after this, which is creating a wrapper for this component that automatically merges refs, puts global attributes, etc.
+
+
+```typescript
+const ComponentWithRefsMerged = (props: OwnerInterface & InnerRefInterface<C> & { 'data-testid'?: string }) => {
+    // we may or not have data-testid at this point, so we need to calculate it
+    const dataTestId = props['data-testid'] ?? (displayName !== null ? displayNameToKebabCase(displayName) : '');
+    // we also need to calculate dataDimsumSlot at this point
+    const dataDimsumSlot = displayName !== null ? displayNameToPropCase(displayName) : '';
+    // then we get the part props for this slot, and we cast it to use refs
+    const partProps = getPartProps({
+    ...props,
+    'data-testid': dataTestId,
+    'data-dimsum-slot': dataDimsumSlot,
+    }) as {
+    innerRef?: AnyStyledRef<HTMLElement>;
+    };
+
+    const mergedRef = useMemo(
+    () => mergeRefs(props.innerRef, partProps.innerRef),
+    [props.innerRef, partProps.innerRef],
+    );
+
+    const propsWithRefMerged = {
+    ...props,
+    ref: mergedRef,
+    innerRef: mergedRef,
+    } as React.ComponentProps<C>;
+
+    return <Component {...propsWithRefMerged} />;
+};
+
+```
+
+But it should be straightforward.
+
+Last 2 lines of code are just adding some properties to the wrapper, so it can be used as a styled component.
+We need to add the `dsStyledComponentId` and `toString` to the wrapper, so we can use it on the interpolation.
+
+```typescript
+ComponentWithRefsMerged.dsStyledComponentId = Component.styledComponentId as string;
+ComponentWithRefsMerged.toString = Component.toString;
+```

package/dist/esm/styled/Documentation.md

@@ -0,0 +1,252 @@
+### Internal Workings of the Styled-Component Wrapper
+
+This document delves into the internal mechanics of our custom styled-component wrapper, providing insights for developers who need to understand or extend its functionality.
+
+#### Overview
+The wrapper is designed to extend the standard functionality of styled-components with additional features like automatic theme coercion, design system integration, and automatic attribute generation. It acts as a higher-order component (HOC) that wraps around the base styled component.
+
+#### Understanding Tagged Template Literals
+In standard styled-components usage, styled components are often defined using tagged template literals, a feature of ES6. For example:
+
+```typescript
+const StyledButton = styled.button`
+  margin: ${({ theme }) => theme.space.xs};
+`;
+```
+
+This syntax is concise and readable, especially for defining component styles that directly leverage props and themes.
+
+But, for the purpose of this document, you should understand the real way this gets "transpiled" to:
+
+```typescript
+styled('button')(['margin: ', ';\n'], ({theme}) => theme.space.xs);
+```
+
+So, `styled` is a function that takes a tag (in this case, `'button'`) and returns a function that takes any number of arguments. The first argument is an array of strings (the constant parts of the template literal), and the rest are the interpolated values (the dynamic parts of the template literal). Each interpolated value will be inserted into the array of strings at the corresponding index.
+
+This is just for the most-used-case on our library though. Styled components also accept object instead of tagged template literals, and we have to handle that as well. So keep that in mind as well.
+
+#### The idea of the Wrapper
+
+The wrapper is designed to also receive as a parameter an options object, along with the tag. So the signature of the wrapper is:
+
+```typescript
+const OurStyled = (tag: Tag, options: {name: string, slot: string}) => ReturnType<styled('tag')>
+```
+
+These name and slot properties will be used for theming the styled component, for applying style and variant overrides from the design system, calculate data-testids, data-dimsum-slot and other attributes as well, ref-merging, etc.
+
+#### Let's see the code
+
+```typescript
+checkNamingConvention(componentName, componentSlot);
+```
+
+This function checks if the `name` and `slot` properties adhere to our project's naming conventions. If they don't, it triggers a warning.
+
+The correct format for componentName is `DSComponentName`, and for componentSlot is `component-slot`. This is important since other functionalities rely on these properties being correctly formatted.
+
+Now, let's look at the overall body of the function
+
+```typescript
+const baseStyledResolver = baseStyled(tag) as unknown as ThemedStyledFunction<C, Theme, {}, keyof any>;
+
+const dsStyledResolver: ThemedStyledFunctionBase<C, Theme> = (styleArg, ...expressions) => {
+    ... some code that we will see later ...
+};
+
+// Here we use arrow functions to preserve the `this` context
+const styledAttributes = {
+attrs: ((...args) => {
+    baseStyledResolver.attrs(...args);
+    return dsStyledResolver;
+}) as (typeof baseStyledResolver)['attrs'],
+withConfig: ((...args) => {
+    baseStyledResolver.withConfig(...args);
+    return dsStyledResolver;
+}) as (typeof baseStyledResolver)['withConfig'],
+};
+
+return Object.assign(dsStyledResolver, styledAttributes);
+
+```
+
+It looks scary. But let's break it down.
+
+1. We create a base styled resolver using the `baseStyled` function. This is just calling the ORIGINAL `styled` function from `styled-components` (we just changed its name when importing it).
+Ultimately, this is the function that will be called when we use our styled component, since we are just building a wrapper of it.
+
+2. We create a new resolver, `dsStyledResolver`, that will be the one that will be returned by our wrapper. It has to receive as a first argument the styleArg, which is the style object or string that we pass to the styled component. The rest of the arguments are the interpolated values of the tagged template literal.
+This function will do a lot of magic, but it will ultimately call the `baseStyledResolver` with the correct arguments.
+
+3. We create an object with two methods, `attrs` and `withConfig`, that will be used to augment the styled component. These methods are just calling the original methods of the `baseStyledResolver`, and then returning the `dsStyledResolver` itself. This is just to make sure that the styled component is augmented with the correct methods.
+
+4. We return an object that is the `dsStyledResolver` with the two methods we created. This is the final object that will be returned by our wrapper.
+
+This is just a basic wrapper flow, with an extra step for the `attrs` and `withConfig` function. The `dsStyledResolver` is the one that will be used to create the styled component, and it will have all the magic we need to make it work with our design system.
+
+Now let's see the `dsStyledResolver` function:
+
+```typescript
+const expressionsWithDsStyledComponentId = dsStyledComponentTransform(expressions);
+```
+
+Well, this function is needed for something we do later in the code, but the basic idea is to support this syntax:
+
+```typescript
+const StyledChat = styled('div')`
+    ${StyledChatBubble} {
+        margin: 0;
+    }
+`;
+```
+
+Now that you understand how the tagged template literals work, you can see that we are interpolating a styled component inside another styled component. This is a common pattern in our codebase, and we need to support it.
+
+Our styled-component, will have a `dsStyledComponentId` added to them, so we can reference them on this transformation.
+
+The `dsStyledComponentTransform` function will transform the styled component into its `dsStyledComponentId` so we can use it on the interpolation.
+
+So basically it will transform `StyledChatBubble`
+
+```typescript
+`.${StyledChatBubble.dsStyledComponentId}`
+```
+
+Notice the `.` before the interpolation. This is because we are interpolating a class name, and we need to add the `.` to make it a valid CSS selector.
+
+```typescript
+    const [styleArgWithMagic, expressionsWithMagic] = magicCssTransform(styleArg, expressionsWithDsStyledComponentId);
+```
+
+This transformation allows our styled components to be MAGICAL. Meaning, we support things like this:
+
+```typescript
+const StyledButton = styled('button')`
+    color: neutral-100;
+`;
+```
+
+Doing this is not so simple, but I will try to explain it in a simple way.
+
+First we need to do a regex search to locate something that we can replace with a theme getter (for now we just support colors, but we can extend it to other things).
+
+Then we need to replace that token with the corresponding value from the theme, using a function, so it's the same as this:
+
+```typescript
+const StyledButton = styled('button')`
+    color: ${({theme}) => theme.colors.neutral[100]};
+`;
+```
+
+Now, let's analyze the styleArg vs expressions thing.
+
+Before this transformation, styleArg was: `color: neutral 100;\n`, and no expressions.
+
+After this transformation, styleArg is `["color: ", ";\n"]` and expressions is `[({theme}) => theme.colors.neutral[100]]`.
+
+So, every time we find a token, we split the styleArg in two, and a function is added to the expressions array.
+
+Let's see the next part of the code:
+
+```typescript
+const expressionsWithThemeCoerced = coerceWithDefaultTheme(expressionsWithMagic);
+```
+
+This transformation just adds a default theme in case no theme was provided on the application. So basically we just replace every function on the expressions array with a new function with the theme coerced.
+
+```
+expresions = [f1, f2, f3]
+
+-->
+
+expressions = [({theme,...rest}) => f1({...rest, theme: theme ?? defaultTheme}), ...]
+```
+
+
+Let's look at the next important part
+
+```typescript
+if (componentName && componentSlot) {
+    expressionsWithThemeCoerced.push(genStyleOverridesExpression(componentName, componentSlot));
+}
+
+if (componentName && componentSlot === 'root') {
+    expressionsWithThemeCoerced.push(genVariantOverridesExpression(componentName));
+}
+
+const numOfExpressionsAdded = expressionsWithThemeCoerced.length - expressionsWithMagic.length;
+
+const fixedStyleArg = fixStyleArg(styleArgWithMagic, numOfExpressionsAdded);
+```
+
+This is where we add both style and variant overrides to the styled component. Here we access the theme object in search of the corresponding variant and style overrides, and we push them into the expressions array.
+
+Notice that we are adding the expressions at the end of the array, so they will be the last ones to be evaluated, therefore they will override any previous styles.
+
+It's also important to note that we need to fix the styleArg after adding the expressions, since we added new expressions, and we need to adjust the styleArg to match the new expressions array.
+
+
+In the next part, we just generate some autocalculated values, like display name, data-testids, classNames, etc. And then, we just add them one by one by using the `attrs` function
+
+```typescript
+const [displayName, attributes] = generateAutoCalculated(options);
+
+const baseStyledResolverWithAttributes = attributes.reduce<typeof baseStyledResolver>(
+    (curStyledResolver, attributeFunc) => curStyledResolver.attrs(attributeFunc),
+    baseStyledResolver,
+);
+```
+
+Notice that we are using the `baseStyledResolver` here!!! We are adding the attributes to the original styled.
+Now, we will call this styled with the styleArg and expression that we calculated before, and we will return the styled component.
+
+```typescript
+const Component = baseStyledResolverWithAttributes(fixedStyleArg, ...expressionsWithThemeCoerced);
+```
+
+So, wrapper ONLY augments the styleArg and expressions, and then calls the original styled function with the augmented arguments.
+
+There is an extra piece of logic after this, which is creating a wrapper for this component that automatically merges refs, puts global attributes, etc.
+
+
+```typescript
+const ComponentWithRefsMerged = (props: OwnerInterface & InnerRefInterface<C> & { 'data-testid'?: string }) => {
+    // we may or not have data-testid at this point, so we need to calculate it
+    const dataTestId = props['data-testid'] ?? (displayName !== null ? displayNameToKebabCase(displayName) : '');
+    // we also need to calculate dataDimsumSlot at this point
+    const dataDimsumSlot = displayName !== null ? displayNameToPropCase(displayName) : '';
+    // then we get the part props for this slot, and we cast it to use refs
+    const partProps = getPartProps({
+    ...props,
+    'data-testid': dataTestId,
+    'data-dimsum-slot': dataDimsumSlot,
+    }) as {
+    innerRef?: AnyStyledRef<HTMLElement>;
+    };
+
+    const mergedRef = useMemo(
+    () => mergeRefs(props.innerRef, partProps.innerRef),
+    [props.innerRef, partProps.innerRef],
+    );
+
+    const propsWithRefMerged = {
+    ...props,
+    ref: mergedRef,
+    innerRef: mergedRef,
+    } as React.ComponentProps<C>;
+
+    return <Component {...propsWithRefMerged} />;
+};
+
+```
+
+But it should be straightforward.
+
+Last 2 lines of code are just adding some properties to the wrapper, so it can be used as a styled component.
+We need to add the `dsStyledComponentId` and `toString` to the wrapper, so we can use it on the interpolation.
+
+```typescript
+ComponentWithRefsMerged.dsStyledComponentId = Component.styledComponentId as string;
+ComponentWithRefsMerged.toString = Component.toString;
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elliemae/ds-system",
-  "version": "3.33.0-next.0",
+  "version": "3.33.0-next.2",
   "license": "MIT",
   "description": "ICE MT - Dimsum - System",
   "files": [
@@ -100,7 +100,7 @@
     "@elliemae/pui-cli": "~9.0.0-next.31",
     "@elliemae/pui-theme": "~2.7.0",
     "styled-components": "~5.3.9",
-    "@elliemae/ds-monorepo-devops": "3.33.0-next.0"
+    "@elliemae/ds-monorepo-devops": "3.33.0-next.2"
   },
   "peerDependencies": {
     "@elliemae/pui-theme": "^2.7.0",