@yahoo/uds 0.2.0 → 0.3.0

package/cli/README.md

@@ -8,10 +8,10 @@ Bluebun relies on Bun APIs and is designed to be extremely fast, with no-depende
 
 # Commands
 
-In any consumer of `@yahoo/uds` the following commands are available:
-
 > Please note: If you are _not_ running the CLI from a package.json script you will need to add `bun` before the binary in order to run it directly. i.e. `bun uds purge`
 
+In any consumer of `@yahoo/uds` the following commands are available:
+
 ## Config
 
 ### Using args
@@ -23,9 +23,7 @@ In any consumer of `@yahoo/uds` the following commands are available:
 
 ```shell
 uds sync --id [id] --outFile [path]
-```
 
-```shell
 uds sync --id [id]
 ```
 
@@ -36,10 +34,6 @@ uds sync --id [id]
 | UDS_ID       | true     |                 |
 | UDS_OUT_FILE | false    | ./uds.config.ts |
 
-```shell
-UDS_ID=[id] uds sync --outFile [path]
-```
-
 ```shell
 UDS_ID=[id] UDS_OUT_FILE=[path] uds sync
 ```

package/cli/bunfig.toml

@@ -0,0 +1,3 @@
+[test]
+# Load these modules before running tests.
+preload = ["./preload"]

package/cli/commands/expo/_setup.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 
+// @ts-expect-error this is a transitive dep of expo, which is required in consumers to even run this setup
 import { EasJsonAccessor, EasJsonUtils, Platform } from '@expo/eas-json';
 import { print, type Props } from 'bluebun';
 import { $, semver, which } from 'bun';

package/cli/commands/expo/build.ts

@@ -4,7 +4,7 @@ import { type MobileProps, needsBinary, needsBrewFormula, setup } from './_setup
 
 export default {
   name: 'build',
-  description: '🚀 Build',
+  description: '🏗️  Build',
   run: async (props: MobileProps) => {
     const { platform, profile, output } = await setup({
       props,

package/cli/commands/expo/launch.ts

@@ -5,7 +5,7 @@ import { setup } from './_setup';
 
 export default {
   name: 'launch',
-  description: '🚀 Launch',
+  description: '📱 Launch',
   run: async (props: MobileProps) => {
     const { platform, output } = await setup({
       props,

package/cli/commands/purge.ts

@@ -11,6 +11,6 @@ export default {
 
     await purge();
 
-    spinStop('✅ Purging css done!');
+    spinStop('✅', 'Purging css done!');
   },
 };

package/cli/commands/sync.ts

@@ -1,4 +1,4 @@
-import { Props } from 'bluebun';
+import { magenta, print, Props } from 'bluebun';
 
 import { setupConfigWorker } from '../utils/setupConfigWorker';
 import { SyncOptions } from '../utils/types';
@@ -9,10 +9,22 @@ interface SyncProps extends Props {
 
 export default {
   name: 'sync',
-  description: '🌈 Sync',
-  run: async ({ options }: SyncProps) => {
+  description: '🔄 Update to latest design config 🎨',
+  alias: ['update'],
+  run: async ({ name, commandPath, options }: SyncProps) => {
+    const { id = Bun.env.UDS_ID, outFile = Bun.env.UDS_OUT_FILE } = options;
+
+    if (!id || typeof id === 'boolean') {
+      console.error(
+        '\nMissing config ID. Please pass an --id flag or set the UDS_ID env variable.\n',
+      );
+      print(`${magenta('Usage:')} ${name} ${commandPath} --id <config-id>\n`);
+      return;
+    }
+
     await setupConfigWorker({
-      ...options,
+      id,
+      outFile: outFile ?? './uds.config.ts',
       onUpdate: ({ worker }) => {
         if (!options.watch) {
           worker.terminate();

package/cli/commands/uds.ts

@@ -1,4 +1,4 @@
-import { type Props } from 'bluebun';
+import { print, type Props, red } from 'bluebun';
 
 import { getCommandHelp } from '../utils/getCommandHelp';
 
@@ -6,6 +6,9 @@ export default {
   name: 'uds',
   description: '',
   run: async (props: Props) => {
+    if (props.first) {
+      print(red(`Unknown command: ${props.first}`));
+    }
     await getCommandHelp(props);
   },
 };

package/cli/commands/version.ts

@@ -4,7 +4,7 @@ import packageJson from '../../package.json';
 
 export default {
   name: 'version',
-  description: `💾 ${packageJson.version}`,
+  description: `${packageJson.version}`,
   run: async () => {
     print(packageJson.version);
   },

package/cli/preload.ts

@@ -0,0 +1,42 @@
+import { jest, mock } from 'bun:test';
+
+const mockFastGlob = jest.fn().mockResolvedValue(['/pages/PageA.tsx', '/pages/PageB.tsx']);
+
+mock.module('fast-glob', () => ({ __esModule: true, default: mockFastGlob }));
+
+mock.module('@yahoo/uds/tailwindPurge', () => ({
+  componentsDependencies: {
+    Button: ['Icon', 'Pressable', 'Text'],
+    Spinner: [],
+    HStack: ['Box'],
+  },
+  componentToVariants: {
+    Button: ['color'],
+    HStack: ['alignItems', 'justifyContent'],
+    Icon: ['color'],
+    Text: ['fontSize', 'fontFamily'],
+    Pressable: ['display'],
+  },
+  variantsList: ['color', 'alignItems', 'justifyContent', 'display', 'fontSize', 'fontFamily'],
+  variantToTailwindClass: {
+    color: 'text-accent text-alert text-black text-brand text-positive text-warning text-white',
+    alignItems: 'items-start items-end items-center items-stretch items-baseline',
+    justifyContent:
+      'justify-start justify-end justify-center justify-between justify-around justify-evenly',
+    display:
+      'block inline-block inline flex inline-flex table inline-table table-caption table-cell table-column table-column-group table-footer-group table-header-group table-row-group table-row flow-root grid contents',
+    fontSize: 'font-size-display1 font-size-title1 ',
+    fontFamily:
+      'font-icons font-sans font-sans-beta font-sans-condensed font-serif-text font-serif-display font-display1 font-title1 font-title2 font-title3 font-title4 font-headline1 font-body1 font-label1 font-label2 font-caption1 font-caption2 font-legal1',
+  },
+  componentToTwClasses: {
+    Box: 'flex',
+    HStack: 'container fill',
+    Icon: 'flex fill outline',
+    Image: 'flex',
+    Pressable: 'flex',
+    Text: 'flex text',
+    VStack: 'container fill',
+    Button: '',
+  },
+}));

package/cli/utils/configWorker.ts

@@ -1,30 +1,49 @@
 // prevents TS errors
 declare var self: Worker;
 
-import { $ } from 'bun';
+import { UniversalTokensConfig } from '@yahoo/uds/tokens';
 
 import { ConfigWorkerThreadMessage } from './types';
 
+const CLOUD_FUNCTION = 'https://syncconfig-j57v6zmjrq-uc.a.run.app';
+
 self.onmessage = async ({ data }: ConfigWorkerThreadMessage) => {
+  const { id } = data.resp;
+
   if (data.type === 'init') {
     try {
-      // Only listen for updates if firebase is available. This will only be available in UDS monorepo atm
+      // The firebase packaage available if we're in the UDS monorepo. Listen for updates.
       const firebase = await import('database/firebase');
-      console.write('Fetching from local database package...\n');
-      firebase.onBranchSnapshot(data.resp.id, ({ config, status }) => {
+
+      // Bail if the branch doesn't exist in configurator.
+      const branchExists = await firebase.branchExists(id);
+      if (!branchExists) {
+        throw new Error(`Config id '${id}' does not exist in the Configurator.`);
+      }
+
+      console.log('Fetching using local database package...');
+
+      firebase.onBranchSnapshot(id, ({ config, status }) => {
         postMessage({ type: 'update', resp: { config, status } });
       });
     } catch (err) {
       try {
-        const res =
-          await $`curl https://syncconfig-j57v6zmjrq-uc.a.run.app?id=${data.resp.id}`.json();
-        if (res?.config) {
-          postMessage({ type: 'update', resp: { config: res.config, status: 'error' } });
-        } else {
-          throw Error;
+        console.log('Fetching from configurator...');
+
+        const resp = await fetch(`${CLOUD_FUNCTION}?id=${id}`);
+        if (!resp.ok) {
+          throw new Error(`Error fetching config id '${id}'. Does it exist in the Configurator?`);
         }
+
+        const { config } = ((await resp.json()) as { config: UniversalTokensConfig }) ?? {};
+        if (!config) {
+          throw new Error('Config JSON could not be parsed.');
+        }
+
+        postMessage({ type: 'update', resp: { config, status: 'error' } });
       } catch (err) {
-        throw new Error('Error fetching config');
+        console.error(`\n${(err as Error).message}\n`);
+        throw err;
       }
     }
   }

package/cli/utils/getCommandHelp.ts

@@ -1,21 +1,21 @@
 import {
-  bold,
   calcWidestCommandName,
-  CommandTree,
+  type CommandTree,
   commandTree,
   cyan,
   gray,
+  green,
+  magenta,
   print,
-  Props,
+  type Props,
   white,
 } from 'bluebun';
 
 /**
- *
  * The formatting from bluebun for the help command is not great.
  * I forked code from https://github.com/jamonholmgren/bluebun/blob/main/src/command-help.ts
  *
- * TODO: Maybe create helpers for better styling control for this & other features
+ * TODO: create helpers for better styling control for this & other features
  *
  * Some packages to checkout:
  * - https://github.com/wobsoriano/blipgloss
@@ -29,7 +29,7 @@ async function formatHelp(initialProps: Props) {
   const _tree = await commandTree(initialProps);
   const tree = categoryToFilter ? { [categoryToFilter]: _tree[categoryToFilter] } : _tree;
 
-  const widest = calcWidestCommandName(tree) + 5;
+  const widest = calcWidestCommandName(tree) + 10;
 
   function generateHelp(cmdTree: CommandTree, prefix: string): string[] {
     return Object.keys(cmdTree).flatMap((key) => {
@@ -49,16 +49,25 @@ async function formatHelp(initialProps: Props) {
 
   const helpLines = generateHelp(tree, name);
 
-  const help = `${bold(white('Commands:'))}
-  
-    ${helpLines.join('\n')}
-    `;
+  // https://texteditor.com/multiline-text-art/
+  const banner = `
+█ █ █▀▄ ▄▀▀   ▄▀▀ █   █
+▀▄█ █▄▀ ▄██   ▀▄▄ █▄▄ █
+Universal Design System
+`.trim();
+
+  const help = `
+${green(banner)}
+
+${magenta(`Usage: ${white(`${name} <command>`)}`)}
+
+${magenta('Commands:')}
+${helpLines.join('\n')}
+`;
 
   return help;
 }
 
 export async function getCommandHelp(props: Props) {
-  print('');
-  const helpText = await formatHelp(props);
-  print(helpText);
+  print(await formatHelp(props));
 }

package/cli/utils/purgeCSS.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from 'bun:test';
+import { Project } from 'ts-morph';
+
+import {
+  getComponentsToConvertToTW,
+  getFiles,
+  getTailwindSafelist,
+  getUsedProps,
+  isUDSComponent,
+  parseFiles,
+} from './purgeCSS';
+
+const PAGE_A_CODE = `
+import { HStack, Button } from '@yahoo/uds';
+
+const functionWithProp = () => {
+  const vars = {
+    isActive: false
+  };
+
+  return {
+    ...vars, 
+    color: 'blue'
+  }
+}
+
+const AnotherComponent = () => {
+  const propsList = functionWithProp();
+  return <HStack test="test" {...propsList}>meow</HStack>
+}
+
+const PageA = () => {
+  return (
+    <div>
+      <HStack />
+      <Button> Click me </Button>
+    </div>
+  )
+}
+`;
+
+const PAGE_B_CODE = `
+import { HStack, Spinner } from '@yahoo/uds';
+import { noop } from 'lodash';
+
+const PageB = () => {
+  return (
+    <div>
+    <HStack flexGrow="1" alignItems="center" justifyContent="center">
+      <Spinner />
+    </HStack>
+    </div>
+  )
+}
+`;
+
+const FILES = ['/pages/PageA.tsx', '/pages/PageB.tsx'];
+const IMPORTED_UDS_COMPONENTS = ['HStack', 'Button', 'Spinner'];
+
+describe('purgeCSS', () => {
+  const project = new Project();
+
+  describe('getFiles', () => {
+    it('returns the list of files', async () => {
+      const files = await getFiles();
+
+      expect(files).toEqual(FILES);
+    });
+  });
+
+  describe('parseFiles', () => {
+    it('returns the list of imports from @yahoo/uds', () => {
+      project.createSourceFile(FILES[0], PAGE_A_CODE, {
+        overwrite: true,
+      });
+      project.createSourceFile(FILES[1], PAGE_B_CODE, {
+        overwrite: true,
+      });
+
+      const res = parseFiles(project, FILES);
+
+      expect(res).toEqual(IMPORTED_UDS_COMPONENTS);
+    });
+  });
+
+  describe('getTailwindSafelist', () => {
+    it('returns the tailwind classes corresponding to the props on a component', () => {
+      const res = getTailwindSafelist(project, IMPORTED_UDS_COMPONENTS);
+
+      expect(res).toEqual(
+        'container fill  items-start items-end items-center items-stretch items-baseline justify-start justify-end justify-center justify-between justify-around justify-evenly text-accent text-alert text-black text-brand text-positive text-warning text-white ',
+      );
+    });
+  });
+
+  describe('getComponentsToConvertToTW', () => {
+    it('should get just exports which are components from UDS', () => {
+      const res = getComponentsToConvertToTW(['Button', 'HStack', 'randomThingy']);
+
+      expect(res).toEqual(['Button', 'Icon', 'Pressable', 'Text', 'HStack', 'Box']);
+    });
+  });
+
+  describe('isUDSComponent', () => {
+    it('returns true if the component is exported from UDS', () => {
+      const res = isUDSComponent('HStack');
+
+      expect(res).toBeTrue();
+    });
+
+    it('returns false if the component is not exported from UDS', () => {
+      const res = isUDSComponent('NotUdsComponent');
+
+      expect(res).toBeFalse();
+    });
+  });
+
+  describe('getUsedProps', () => {
+    it('return the list of all used props in the project for a given component', () => {
+      project.createSourceFile(FILES[0], PAGE_A_CODE, {
+        overwrite: true,
+      });
+      project.createSourceFile(FILES[1], PAGE_B_CODE, {
+        overwrite: true,
+      });
+
+      const usedProps = getUsedProps(project, 'HStack');
+
+      expect(usedProps).toEqual([
+        'test',
+        'color',
+        'isActive',
+        'flexGrow',
+        'alignItems',
+        'justifyContent',
+      ]);
+    });
+  });
+});

package/cli/utils/purgeCSS.ts

@@ -2,13 +2,18 @@ import path from 'node:path';
 
 import {
   componentsDependencies,
+  componentToTwClasses,
   componentToVariants,
   variantsList,
   variantToTailwindClass,
 } from '@yahoo/uds/tailwindPurge';
+import {
+  findReferencesAsJsxElements,
+  getUsedPropsInReference,
+} from '@yahoo/uds/tailwindPurge/utils';
 import { spinStart } from 'bluebun';
 import FastGlob from 'fast-glob';
-import { Project } from 'ts-morph';
+import { JsxOpeningElement, JsxSelfClosingElement, Project, ts } from 'ts-morph';
 
 type SafeList = string;
 type ImportsList = string[];
@@ -17,7 +22,7 @@ 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 getFiles = async (): Promise<Files> => {
+export const getFiles = async (): Promise<Files> => {
   const workspaceDir = Bun.env.PWD;
   const srcDir = path.join(workspaceDir, '/src/');
   const files = await FastGlob(`${srcDir}/**/*.{jsx,tsx}`);
@@ -25,10 +30,41 @@ 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
  */
-const parseFiles = (project: Project, files: Files): ImportsList => {
+export const parseFiles = (project: Project, files: Files): ImportsList => {
   const importsSet = new Set();
 
   const importsPerFile: string[] = files
@@ -59,27 +95,55 @@ const parseFiles = (project: Project, files: Files): ImportsList => {
   return Array.from(importsSet) as string[];
 };
 
-const getTailwindSafelist = (componentList: string[]): SafeList => {
+export const getTailwindSafelist = (project: Project, componentList: string[]): SafeList => {
+  let 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 += `${componentToTwClasses[component]} `;
     }
   });
 
-  let safeList = '';
   for (const prop of usedProps) {
     safeList += `${variantToTailwindClass[prop]} `;
   }
   return safeList;
 };
 
-const isUDSComponent = (component: string): boolean => {
+/**
+ * Get the used props for a given component.
+ *
+ * @example
+ * const usedProps = getUsedProps(project, 'HStack');
+ */
+export const getUsedProps = (project: Project, component: string) => {
+  const references = findNamedImportReferences(project, '@yahoo/uds', 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];
 };
 
@@ -94,7 +158,7 @@ const saveToFile = async (safeList: SafeList) => {
   await Bun.write(OUTPUT_FILE_PATH, fileContent);
 };
 
-const getComponentsToConvertToTW = (udsImport: ImportsList): string[] => {
+export const getComponentsToConvertToTW = (udsImport: ImportsList): string[] => {
   // filter out just the components
   const components = udsImport.filter((importedItem) => !!componentToVariants[importedItem]);
   const set = new Set();
@@ -128,7 +192,7 @@ async function purge() {
   // 3. Now that we have the importer components
   const udsComponents = getComponentsToConvertToTW(udsImports);
   // 4. Generate the CSS we need
-  const safeList = getTailwindSafelist(udsComponents);
+  const safeList = getTailwindSafelist(project, udsComponents);
   // 5. Write the allowlist to a file
   await saveToFile(safeList);
 }

package/cli/utils/setupConfigWorker.ts

@@ -2,52 +2,22 @@ import path from 'node:path';
 
 import { sortKeys } from './sortKeys';
 import { ConfigWorkerMainThreadMessage, SyncOptions } from './types';
-
-const workerPath = path.resolve(import.meta.dir, './configWorker');
-const workerURL = new URL(Bun.pathToFileURL(workerPath)).href;
-
 interface ConfigWorkerOptions extends SyncOptions {
   onUpdate?: (params: { worker: Worker }) => void;
 }
 
-export async function setupConfigWorker({
-  id = Bun.env.UDS_ID,
-  outFile = Bun.env.UDS_OUT_FILE,
-  onUpdate,
-}: ConfigWorkerOptions = {}) {
-  const workspaceDir = Bun.env.PWD;
-  let configID = id;
-  let configOutFile = outFile ?? './uds.config.ts';
-
-  // If we didn't get the config ID from the command line or env vars, check for a uds.json file
-  if (!configID) {
-    const udsConfigFile = Bun.file(`${workspaceDir}/uds.json`);
-    const udsConfigFileExists = await udsConfigFile.exists();
-    if (udsConfigFileExists) {
-      const configJsonFile = (await udsConfigFile.json()) as { id: string; outFile: string };
-
-      configID = configJsonFile.id;
-      configOutFile = configJsonFile.outFile;
-    }
-  }
-
-  // have _nothing_, warn the eng to do something
-  if (!configID) {
-    console.error(
-      '\nMissing config ID. Please pass in --id, set UDS_ID in your .env, or create a uds.json file with { "id": "your-config-id" } defined.\n',
-    );
-    process.exit(1);
-  }
-
-  const outFilePath = `${workspaceDir}/${configOutFile}`;
+export async function setupConfigWorker({ id, outFile, onUpdate }: ConfigWorkerOptions) {
+  const workerPath = path.resolve(import.meta.dir, './configWorker');
+  const workerURL = Bun.pathToFileURL(workerPath).href;
+  const outFilePath = `${Bun.env.PWD}/${outFile}`;
 
   const worker = new Worker(workerURL);
 
   worker.addEventListener('open', () => {
-    worker.postMessage({ type: 'init', resp: { id: configID } });
+    worker.postMessage({ type: 'init', resp: { id } });
   });
 
-  worker.onmessage = async ({ data }: ConfigWorkerMainThreadMessage) => {
+  worker.addEventListener('message', async ({ data }: ConfigWorkerMainThreadMessage) => {
     if (data.type === 'update') {
       // Firebase does not guarantee the order of the keys in the config
       // this can give us a false diff when writing to existing file
@@ -59,11 +29,11 @@ import { type UniversalTokensConfig } from '@yahoo/uds';
 export const config: UniversalTokensConfig = ${JSON.stringify(sortedConfig, null, 2)};
 `.trimStart();
 
-      console.log(`✅ Synced UDS config ${configID} to ${outFilePath}`);
+      console.log(`✅ Synced UDS config ${id} to ${outFilePath}`);
       await Bun.write(outFilePath, configContent);
       onUpdate?.({ worker });
     }
-  };
+  });
 
   // Register a handler for the SIGINT signal (Ctrl + C)
   process.on('SIGINT', () => {

package/cli/utils/types.ts

@@ -7,7 +7,10 @@ export type ConfigWorkerMainThreadMessage = MessageEvent<{
 }>;
 
 export type SyncOptions = {
-  id?: string;
-  outFile?: string;
+  /** Configurator (branch) id */
+  id: string;
+  /** The file to write the config to. Defaults to uds.config.ts. */
+  outFile: string;
+  /** Enable watch mode? */
   watch?: boolean;
 };