@yahoo/uds 0.2.2 → 0.4.0

package/cli/utils/purgeCSS.ts

@@ -2,20 +2,54 @@ import path from 'node:path';
 
 import {
   componentsDependencies,
+  componentToTwClasses,
   componentToVariants,
   variantsList,
   variantToTailwindClass,
 } from '@yahoo/uds/tailwindPurge';
-import { spinStart } from 'bluebun';
+import {
+  findReferencesAsJsxElements,
+  getUsedPropsInReference,
+} from '@yahoo/uds/tailwindPurge/utils';
+import {
+  ColorModeConfig,
+  DARK_COLOR_MODE_CLASSNAME,
+  LARGE_SCALE_MODE_CLASSNAME,
+  LIGHT_COLOR_MODE_CLASSNAME,
+  MEDIUM_SCALE_MODE_CLASSNAME,
+  ScaleModeConfig,
+  SMALL_SCALE_MODE_CLASSNAME,
+  UniversalTokensConfig,
+  XLARGE_SCALE_MODE_CLASSNAME,
+  XSMALL_SCALE_MODE_CLASSNAME,
+  XXLARGE_SCALE_MODE_CLASSNAME,
+  XXXLARGE_SCALE_MODE_CLASSNAME,
+} from '@yahoo/uds/tokens';
+import { print, spinStart, spinStop } from 'bluebun';
 import FastGlob from 'fast-glob';
-import { Project } from 'ts-morph';
+import { JsxOpeningElement, JsxSelfClosingElement, Project, ts } from 'ts-morph';
+
+const scaleModeToClass: { [key in keyof ScaleModeConfig]: string } = {
+  large: LARGE_SCALE_MODE_CLASSNAME,
+  medium: MEDIUM_SCALE_MODE_CLASSNAME,
+  small: SMALL_SCALE_MODE_CLASSNAME,
+  xLarge: XLARGE_SCALE_MODE_CLASSNAME,
+  xSmall: XSMALL_SCALE_MODE_CLASSNAME,
+  xxLarge: XXLARGE_SCALE_MODE_CLASSNAME,
+  xxxLarge: XXXLARGE_SCALE_MODE_CLASSNAME,
+};
+
+const colorModeToClass: { [key in keyof ColorModeConfig]: string } = {
+  dark: DARK_COLOR_MODE_CLASSNAME,
+  light: LIGHT_COLOR_MODE_CLASSNAME,
+};
 
-type SafeList = string;
+type SafeList = string[];
 type ImportsList = string[];
 type Files = string[];
 
 // TODO: use CLI args to power the output file path
-const OUTPUT_FILE_PATH = Bun.file(`${Bun.env.PWD}/dist/safelist.js`);
+const OUTPUT_FILE_PATH = Bun.file(`${Bun.env.PWD}/dist/safelist.ts`);
 
 export const getFiles = async (): Promise<Files> => {
   const workspaceDir = Bun.env.PWD;
@@ -25,6 +59,37 @@ export const getFiles = async (): Promise<Files> => {
   return files;
 };
 
+/**
+ * Find all JSX references for a named import.
+ *
+ * @example
+ * const references = findNamedImportReferences(project, '@yahoo/uds', 'HStack')
+ */
+export function findNamedImportReferences(
+  project: Project,
+  moduleSpecifierValue: string,
+  namedImportName: string,
+) {
+  const references: (JsxOpeningElement | JsxSelfClosingElement)[] = [];
+  for (const sourceFile of project.getSourceFiles()) {
+    for (const importDeclaration of sourceFile.getImportDeclarations()) {
+      if (importDeclaration.getModuleSpecifierValue() === moduleSpecifierValue) {
+        for (const namedImport of importDeclaration.getNamedImports()) {
+          if (namedImport.getName() === namedImportName) {
+            const identifier = namedImport.getFirstDescendantByKindOrThrow(
+              ts.SyntaxKind.Identifier,
+            );
+
+            references.push(...findReferencesAsJsxElements(identifier));
+          }
+        }
+      }
+    }
+  }
+
+  return references;
+}
+
 /**
  * Given a file it returns the list of imports from @yahoo/uds
  */
@@ -39,7 +104,10 @@ export const parseFiles = (project: Project, files: Files): ImportsList => {
         sourceFile
           ?.getImportDeclarations()
           .filter((declaration) => {
-            return declaration.getModuleSpecifier().getText().includes('@yahoo/uds');
+            return (
+              declaration.getModuleSpecifier().getText().includes('@yahoo/uds') ||
+              declaration.getModuleSpecifier().getText().includes('@yahoo/uds/experimental')
+            );
           })
           .map((declaration) => {
             return declaration.getNamedImports().map((namedImport) => namedImport.getName());
@@ -59,26 +127,58 @@ export const parseFiles = (project: Project, files: Files): ImportsList => {
   return Array.from(importsSet) as string[];
 };
 
-export const getTailwindSafelist = (componentList: string[]): SafeList => {
+export const getTailwindSafelist = (project: Project, componentList: string[]): SafeList => {
+  const safeList: SafeList = [];
   const validVariants = new Set<string>(variantsList);
   const usedProps = new Set<string>();
   componentList.forEach((component: string) => {
     if (isUDSComponent(component)) {
+      // get the TW classes relevant for each prop
+      // these classes are used internally in UDS,
+      // they either have been initialized or used by other UDS components
       componentToVariants[component].forEach((prop: string) => {
         if (validVariants.has(prop) && !usedProps.has(prop)) {
           usedProps.add(prop);
         }
       });
+
+      // scan the project for used props and
+      // get the corresponding css for those used props
+      getUsedProps(project, component).forEach((prop: string) => {
+        if (validVariants.has(prop) && !usedProps.has(prop)) {
+          usedProps.add(prop);
+        }
+      });
+
+      // get the inline TW classes used in each component
+      safeList.push(...componentToTwClasses[component].replaceAll('\\', '').split(' '));
     }
   });
 
-  let safeList = '';
   for (const prop of usedProps) {
-    safeList += `${variantToTailwindClass[prop]} `;
+    safeList.push(...variantToTailwindClass[prop].replaceAll('\\', '').split(' '));
   }
+
   return safeList;
 };
 
+/**
+ * Get the used props for a given component.
+ *
+ * @example
+ * const usedProps = getUsedProps(project, 'HStack');
+ */
+export const getUsedProps = (project: Project, component: string) => {
+  const references: (JsxOpeningElement | JsxSelfClosingElement)[] = [];
+  references.push(...findNamedImportReferences(project, '@yahoo/uds', component));
+  references.push(...findNamedImportReferences(project, '@yahoo/uds/experimental', component));
+
+  // for each reference find the used/references props
+  const usedProps = references.map((reference) => getUsedPropsInReference(reference)).flat();
+
+  return usedProps;
+};
+
 export const isUDSComponent = (component: string): boolean => {
   return !!componentToVariants[component];
 };
@@ -88,7 +188,7 @@ const saveToFile = async (safeList: SafeList) => {
     //! This file is generated by purgeCSS.ts from @yahoo/uds
     //! Do not edit directly
     //! If there is issue with this file please report to #ask-uds
-    const safeList = "${safeList}";
+    export const safelist = ${JSON.stringify(safeList)};
     `;
 
   await Bun.write(OUTPUT_FILE_PATH, fileContent);
@@ -113,24 +213,74 @@ export const getComponentsToConvertToTW = (udsImport: ImportsList): string[] =>
   return Array.from(set) as string[];
 };
 
-async function purge() {
+/**
+ * Get the classes that corresponds to the used modes
+ */
+export const getClassesForEnabledThemesAndScales = (config: UniversalTokensConfig): string[] => {
+  const classes: string[] = [];
+
+  // TODO: Remove this once the config supports toggling colorModes and scaleModes
+  if (Bun.env.ENABLED_SCALE_AND_COLOR_MODES) {
+    Bun.env.ENABLED_SCALE_AND_COLOR_MODES.split(',').map((mode) => {
+      mode = mode.trim();
+      if (colorModeToClass[mode as keyof ColorModeConfig]) {
+        classes.push(colorModeToClass[mode as keyof ColorModeConfig]);
+      } else if (scaleModeToClass[mode as keyof ScaleModeConfig]) {
+        classes.push(scaleModeToClass[mode as keyof ScaleModeConfig]);
+      }
+    });
+  } else {
+    for (const colorMode in config.colorMode) {
+      classes.push(colorModeToClass[colorMode as keyof ColorModeConfig]);
+    }
+    for (const scaleMode in config.scaleMode) {
+      classes.push(scaleModeToClass[scaleMode as keyof ScaleModeConfig]);
+    }
+  }
+
+  return classes;
+};
+
+type PurgeOptions = {
+  config?: string;
+};
+
+async function purge({
+  config: configPath = Bun.env.UDS_OUT_FILE ?? './uds.config.ts',
+}: PurgeOptions) {
   const workspaceDir = Bun.env.PWD;
   const srcDir = path.join(workspaceDir, '/tsconfig.json');
   const project = new Project({
     tsConfigFilePath: srcDir,
   });
 
+  // we need to load the UDS config
+  const configAbsolutePath = path.resolve(workspaceDir, configPath);
+  const { config } = await import(configAbsolutePath);
+
   spinStart('Getting used UDS components...');
-  /// 1. Get all files from the current dir
+
+  // 1. Get all files from the current dir
+  print('Loading the project...');
   const files = await getFiles();
+
   // 2. For each file get the imports;
+  print('Going through the imports...');
   const udsImports = parseFiles(project, files);
-  // 3. Now that we have the importer components
+
+  // 3. Now that we have the imported components
+  print('Finding all the components imported from UDS...');
   const udsComponents = getComponentsToConvertToTW(udsImports);
+
   // 4. Generate the CSS we need
-  const safeList = getTailwindSafelist(udsComponents);
+  print('🧑‍🍳 Cooking...');
+  const safeList = getTailwindSafelist(project, udsComponents);
+  const themesAndScalesClasses = getClassesForEnabledThemesAndScales(config);
+
   // 5. Write the allowlist to a file
-  await saveToFile(safeList);
+  await saveToFile(safeList.concat(themesAndScalesClasses));
+
+  spinStop('Generated your safelist!');
 }
 
-export { purge };
+export { purge, type PurgeOptions };

package/dist/Image.native-B3I4JoH3.d.cts

@@ -0,0 +1,38 @@
+import * as react from 'react';
+import { i as UniversalPressableProps, j as UniversalIconButtonProps, k as UniversalImageProps } from './types-COiuE8XK.cjs';
+import { View, PressableProps as PressableProps$1, StyleProp, ViewStyle } from 'react-native';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ImageProps as ImageProps$1 } from 'expo-image';
+
+type NativePressableProps = Omit<PressableProps$1, 'children' | 'style' | 'onPress'> & {
+    style?: StyleProp<ViewStyle>;
+};
+interface PressableProps extends UniversalPressableProps, NativePressableProps {
+}
+declare const Pressable: react.ForwardRefExoticComponent<PressableProps & react.RefAttributes<View>>;
+
+interface IconButtonProps extends PressableProps, UniversalIconButtonProps {
+}
+/**
+ * An icon button element that can be used to trigger an action.
+ * @example
+ ```tsx
+  import { IconButton } from "@yahoo/uds";
+
+  export function IconButtonDemo() {
+    return (
+      <IconButton variant="accent-outline" color="primary" name="close" onPress={console.log} />
+    )
+  }
+ ```
+ */
+declare const IconButton: react.ForwardRefExoticComponent<IconButtonProps & react.RefAttributes<View>>;
+
+interface ImageProps extends Omit<ImageProps$1, 'alt' | 'source'>, UniversalImageProps {
+}
+/**
+ * An image element
+ */
+declare function Image({ width: imageWidth, height: imageHeight, src, alt, contentFit, backgroundColor, borderRadius, borderTopStartRadius, borderTopEndRadius, borderBottomStartRadius, borderBottomEndRadius, borderColor, borderColorOnActive, borderColorOnFocus, borderColorOnChecked, borderColorOnHover, borderStartColor, borderEndColor, borderTopColor, borderBottomColor, borderWidth, borderVerticalWidth, borderHorizontalWidth, borderStartWidth, borderEndWidth, borderTopWidth, borderBottomWidth, alignContent, alignItems, alignSelf, flex, flexDirection, flexGrow, flexShrink, flexWrap, justifyContent, flexBasis, display, overflow, overflowX, overflowY, position, spacing, spacingHorizontal, spacingVertical, spacingBottom, spacingEnd, spacingStart, spacingTop, offset, offsetVertical, offsetHorizontal, offsetBottom, offsetEnd, offsetStart, offsetTop, columnGap, rowGap, minHeight, maxHeight, minWidth, maxWidth, ...props }: ImageProps): react_jsx_runtime.JSX.Element;
+
+export { type ImageProps as I, type PressableProps as P, IconButton as a, type IconButtonProps as b, Image as c, Pressable as d };

package/dist/Image.native-DUAFJodS.d.ts

@@ -0,0 +1,38 @@
+import * as react from 'react';
+import { i as UniversalPressableProps, j as UniversalIconButtonProps, k as UniversalImageProps } from './types-COiuE8XK.js';
+import { View, PressableProps as PressableProps$1, StyleProp, ViewStyle } from 'react-native';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ImageProps as ImageProps$1 } from 'expo-image';
+
+type NativePressableProps = Omit<PressableProps$1, 'children' | 'style' | 'onPress'> & {
+    style?: StyleProp<ViewStyle>;
+};
+interface PressableProps extends UniversalPressableProps, NativePressableProps {
+}
+declare const Pressable: react.ForwardRefExoticComponent<PressableProps & react.RefAttributes<View>>;
+
+interface IconButtonProps extends PressableProps, UniversalIconButtonProps {
+}
+/**
+ * An icon button element that can be used to trigger an action.
+ * @example
+ ```tsx
+  import { IconButton } from "@yahoo/uds";
+
+  export function IconButtonDemo() {
+    return (
+      <IconButton variant="accent-outline" color="primary" name="close" onPress={console.log} />
+    )
+  }
+ ```
+ */
+declare const IconButton: react.ForwardRefExoticComponent<IconButtonProps & react.RefAttributes<View>>;
+
+interface ImageProps extends Omit<ImageProps$1, 'alt' | 'source'>, UniversalImageProps {
+}
+/**
+ * An image element
+ */
+declare function Image({ width: imageWidth, height: imageHeight, src, alt, contentFit, backgroundColor, borderRadius, borderTopStartRadius, borderTopEndRadius, borderBottomStartRadius, borderBottomEndRadius, borderColor, borderColorOnActive, borderColorOnFocus, borderColorOnChecked, borderColorOnHover, borderStartColor, borderEndColor, borderTopColor, borderBottomColor, borderWidth, borderVerticalWidth, borderHorizontalWidth, borderStartWidth, borderEndWidth, borderTopWidth, borderBottomWidth, alignContent, alignItems, alignSelf, flex, flexDirection, flexGrow, flexShrink, flexWrap, justifyContent, flexBasis, display, overflow, overflowX, overflowY, position, spacing, spacingHorizontal, spacingVertical, spacingBottom, spacingEnd, spacingStart, spacingTop, offset, offsetVertical, offsetHorizontal, offsetBottom, offsetEnd, offsetStart, offsetTop, columnGap, rowGap, minHeight, maxHeight, minWidth, maxWidth, ...props }: ImageProps): react_jsx_runtime.JSX.Element;
+
+export { type ImageProps as I, type PressableProps as P, IconButton as a, type IconButtonProps as b, Image as c, Pressable as d };

package/dist/VStack-BHlRUsOR.d.cts

@@ -0,0 +1,103 @@
+import * as react from 'react';
+import { Ref } from 'react';
+import { aS as UniversalBoxProps, i as UniversalPressableProps, aU as UniversalTextProps, l as UniversalStackProps } from './types-COiuE8XK.cjs';
+
+type DivProps = React.HTMLAttributes<HTMLDivElement>;
+interface BoxProps extends UniversalBoxProps, DivProps {
+}
+/**
+ * A layout primitive that can be used to compose other components. By default,
+ * `Box` is a flexbox container.
+ *
+ * **When to use**
+ * - if you need to div-like container to apply padding, shapes, or other styling.
+ * - if you're creating card components.
+ *
+ * **Basic usage**
+ * ```tsx
+ * import { Box } from '@yahoo/uds';
+ *
+ * <Box backgroundColor="primary" spacing="6">
+ *   Any kind of content can go here!
+ * </Box>
+ */
+declare const Box: react.ForwardRefExoticComponent<BoxProps & react.RefAttributes<HTMLDivElement>>;
+
+type HtmlButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'color' | 'name'>;
+interface PressableProps extends UniversalPressableProps, HtmlButtonProps {
+}
+/**
+ * Provides a primative for creating button interactions with accessibility support.
+ *
+ * **When to use**
+ * - if you need a highly customized version of [Button](./button)
+ *
+ * **Basic usage**
+ * ```tsx
+ * import { Pressable } from '@yahoo/uds';
+ *
+ * <Pressable
+ *   backgroundColor="secondary"
+ *   borderWidth="thin"
+ *   borderColor="primary"
+ *   borderRadius="lg"
+ *   onPress={() => console.log('Pressed!')}
+ *  >
+ *    <Text variant="body1" color="primary" spacingHorizontal="7" spacingVertical="5">Click me...</Text>
+ * </Pressable>
+ */
+declare const Pressable: react.ForwardRefExoticComponent<PressableProps & react.RefAttributes<HTMLButtonElement>>;
+
+type TextElementTagName = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'p' | 'strong' | 'span' | 'label' | 'li';
+type TextProps = UniversalTextProps & {
+    /** Ref passed to the inner container. */
+    ref?: Ref<HTMLElement>;
+    /** Changes the HTML tag used to render text. Uses the most appropriate semantic tag based on the text style variant. */
+    as?: TextElementTagName;
+} & Omit<JSX.IntrinsicElements[TextElementTagName], 'color'>;
+/**
+ * A text element that can be used to display text.
+ *
+ * **Basic usage**
+ * ```tsx
+ * import { Text } from '@yahoo/uds';
+ *
+ * <Text variant="body1" color="primary">
+ *   Text goes here
+ * </Text>
+ * ```
+ *
+ * By default, the `Text` component uses text primary color and selects the
+ * correct font, weight, and leading. It also choices appropriate semantic
+ * HTML element based on the `variant` prop. For example, `body1` will use a
+ * `<p>` tag, `title1` uses an `<h1>`, etc. This behavior can be overridden
+ * with the `as` prop.
+ */
+declare const Text: react.ForwardRefExoticComponent<Omit<TextProps, "ref"> & react.RefAttributes<HTMLElement>>;
+
+type VStackProps = UniversalStackProps & DivProps;
+/**
+ * VStack is a layout component that arranges its children in rows using [flexbox](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Flexbox)
+ * and can be used to compose larger layouts. VStack is similiar to [Box](./box) but provides additional features like a `gap` property to
+ * add spacing between children.
+ *
+ *  **When to use**
+ * - create a column of items, optionally with gaps between.
+ * - create rows that are sized to their content (height only). By default each child will fill the width of the VStack.
+ * - create rows that fill the available space within the parent container.
+ * - create rows of proportionate size to each other (also known as a ratio-based layout).
+ *
+ * **Basic usage**
+ * ```tsx
+ * import { VStack, Text } from '@yahoo/uds';
+
+ * <VStack gap="6">
+ *   <Text variant="body1" color="primary">First</Text>
+ *   <Text variant="body1" color="primary">Second</Text>
+ *   <Text variant="body1" color="primary">Third</Text>
+ * </VStack>
+ * ```
+ **/
+declare const VStack: react.ForwardRefExoticComponent<UniversalStackProps & DivProps & react.RefAttributes<HTMLDivElement>>;
+
+export { Box as B, type DivProps as D, Pressable as P, Text as T, VStack as V, type BoxProps as a, type PressableProps as b, type TextProps as c, type VStackProps as d };

package/dist/VStack-DMb_RGRS.d.ts

@@ -0,0 +1,103 @@
+import * as react from 'react';
+import { Ref } from 'react';
+import { aS as UniversalBoxProps, i as UniversalPressableProps, aU as UniversalTextProps, l as UniversalStackProps } from './types-COiuE8XK.js';
+
+type DivProps = React.HTMLAttributes<HTMLDivElement>;
+interface BoxProps extends UniversalBoxProps, DivProps {
+}
+/**
+ * A layout primitive that can be used to compose other components. By default,
+ * `Box` is a flexbox container.
+ *
+ * **When to use**
+ * - if you need to div-like container to apply padding, shapes, or other styling.
+ * - if you're creating card components.
+ *
+ * **Basic usage**
+ * ```tsx
+ * import { Box } from '@yahoo/uds';
+ *
+ * <Box backgroundColor="primary" spacing="6">
+ *   Any kind of content can go here!
+ * </Box>
+ */
+declare const Box: react.ForwardRefExoticComponent<BoxProps & react.RefAttributes<HTMLDivElement>>;
+
+type HtmlButtonProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'color' | 'name'>;
+interface PressableProps extends UniversalPressableProps, HtmlButtonProps {
+}
+/**
+ * Provides a primative for creating button interactions with accessibility support.
+ *
+ * **When to use**
+ * - if you need a highly customized version of [Button](./button)
+ *
+ * **Basic usage**
+ * ```tsx
+ * import { Pressable } from '@yahoo/uds';
+ *
+ * <Pressable
+ *   backgroundColor="secondary"
+ *   borderWidth="thin"
+ *   borderColor="primary"
+ *   borderRadius="lg"
+ *   onPress={() => console.log('Pressed!')}
+ *  >
+ *    <Text variant="body1" color="primary" spacingHorizontal="7" spacingVertical="5">Click me...</Text>
+ * </Pressable>
+ */
+declare const Pressable: react.ForwardRefExoticComponent<PressableProps & react.RefAttributes<HTMLButtonElement>>;
+
+type TextElementTagName = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'p' | 'strong' | 'span' | 'label' | 'li';
+type TextProps = UniversalTextProps & {
+    /** Ref passed to the inner container. */
+    ref?: Ref<HTMLElement>;
+    /** Changes the HTML tag used to render text. Uses the most appropriate semantic tag based on the text style variant. */
+    as?: TextElementTagName;
+} & Omit<JSX.IntrinsicElements[TextElementTagName], 'color'>;
+/**
+ * A text element that can be used to display text.
+ *
+ * **Basic usage**
+ * ```tsx
+ * import { Text } from '@yahoo/uds';
+ *
+ * <Text variant="body1" color="primary">
+ *   Text goes here
+ * </Text>
+ * ```
+ *
+ * By default, the `Text` component uses text primary color and selects the
+ * correct font, weight, and leading. It also choices appropriate semantic
+ * HTML element based on the `variant` prop. For example, `body1` will use a
+ * `<p>` tag, `title1` uses an `<h1>`, etc. This behavior can be overridden
+ * with the `as` prop.
+ */
+declare const Text: react.ForwardRefExoticComponent<Omit<TextProps, "ref"> & react.RefAttributes<HTMLElement>>;
+
+type VStackProps = UniversalStackProps & DivProps;
+/**
+ * VStack is a layout component that arranges its children in rows using [flexbox](https://developer.mozilla.org/en-US/docs/Learn/CSS/CSS_layout/Flexbox)
+ * and can be used to compose larger layouts. VStack is similiar to [Box](./box) but provides additional features like a `gap` property to
+ * add spacing between children.
+ *
+ *  **When to use**
+ * - create a column of items, optionally with gaps between.
+ * - create rows that are sized to their content (height only). By default each child will fill the width of the VStack.
+ * - create rows that fill the available space within the parent container.
+ * - create rows of proportionate size to each other (also known as a ratio-based layout).
+ *
+ * **Basic usage**
+ * ```tsx
+ * import { VStack, Text } from '@yahoo/uds';
+
+ * <VStack gap="6">
+ *   <Text variant="body1" color="primary">First</Text>
+ *   <Text variant="body1" color="primary">Second</Text>
+ *   <Text variant="body1" color="primary">Third</Text>
+ * </VStack>
+ * ```
+ **/
+declare const VStack: react.ForwardRefExoticComponent<UniversalStackProps & DivProps & react.RefAttributes<HTMLDivElement>>;
+
+export { Box as B, type DivProps as D, Pressable as P, Text as T, VStack as V, type BoxProps as a, type PressableProps as b, type TextProps as c, type VStackProps as d };