@yahoo/uds 0.2.2 → 0.4.0

package/cli/README.md

@@ -1,181 +1,128 @@
+import { Box } from '@yahoo/uds';
+import { RequiredChip } from '~/components/RequiredChip';
+import { DocImage } from '~/components/DocImage';
+
 # Universal CLI
 
-We leverage Bluebun, which is a CLI framework inspired by [Gluegun](https://github.com/infinitered/gluegun), but specifically designed to be used with [Bun](https://bun.sh), the new JS runtime.
+> **Early preview notice**: The CLI tool currently requires Bun. This requirement may change in the future but you will need to install and use Bun locally to use the `uds` command.
 
-Bluebun relies on Bun APIs and is designed to be extremely fast, with no-dependencies.
+The Universal CLI is available as command, `uds`. The tool was created with [Bluebun](https://github.com/jamonholmgren/bluebun/) (inspired by [Gluegun](https://github.com/infinitered/gluegun)), but is specifically designed to be used with [Bun](https://bun.sh). Bluebun relies on Bun APIs and is designed to be extremely fast, with no-dependencies.
 
-> Trying to add a new command? Please see the "Adding a Command" section below
+<Box justifyContent="center">
+  <DocImage light={{ src: '/images/cli-screenshot.png', width: 500, height: 356 }} />
+</Box>
 
-# Commands
+## Requirements
 
-> 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`
+1. To use the CLI, first [install](/docs/getting-started/quick-start#installation) the `@yahoo/uds` package as a dependency in your package.json. This makes the tool available in your repo.
 
-In any consumer of `@yahoo/uds` the following commands are available:
+- Install Bun if you don't already have it:
 
-## Config
+  ```bash
+  curl -fsSL https://bun.sh/install | bash
+  ```
 
-### Using args
+## Commands
 
-| Arg     | Required | Default         |
-| ------- | -------- | --------------- |
-| id      | true     |                 |
-| outFile | false    | ./uds.config.ts |
+> **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`
 
-```shell
-uds sync --id [id] --outFile [path]
+The following command are available after installing `@yahoo/uds`:
 
-uds sync --id [id]
-```
+### Sync
 
-### Using ENV vars
+The `uds sync` command fetches the latest design config from the [Configurator](/docs/getting-started/using-configurator) and writes it to a file in your project.
 
-| Env Var      | Required | Default         |
-| ------------ | -------- | --------------- |
-| UDS_ID       | true     |                 |
-| UDS_OUT_FILE | false    | ./uds.config.ts |
+#### Flags
 
-```shell
-UDS_ID=[id] UDS_OUT_FILE=[path] uds sync
-```
+| Flag      | Description                 | Default         | Required         |
+| --------- | --------------------------- | --------------- | ---------------- |
+| `id`      | ID from the Configurator    |                 | <RequiredChip /> |
+| `outFile` | File to write the output to | ./uds.config.ts |                  |
 
-## Expo
+**Example:**
 
 ```shell
-uds expo build --profile [profile] --platform [ios|android]
-uds expo dev --profile [profile] --platform [ios|android]
-uds expo launch --profile [profile] --platform [ios|android]
-uds expo update --profile [profile] --platform [ios|android]
-uds expo --help
-```
-
-## Purge CSS
-
-```shell
-uds purge
+uds sync --id [id] --outFile [path]
+uds sync --id [id]
 ```
 
-## Adding a command
+#### Enviornment variables
 
-> Please note: Adding nested commands, i.e. uds expo dev, appears to not work correctly when UDS is consumed from npm. As a workaround, please see code for expo/expo.ts for re-routing sub-commands from the root command file. To verify your CLI command works correctly you should run `npm pack` within the packages/uds directory. Once you have your generated tarball you should copy that tarball to a test application such as https://github.com/yahoo-design/uds-nextjs-demo, then add `"@yahoo/uds": "file:./tarball-generated-from-npm-pack.tgz` to it's dependencies and run an install. Now you should be able to run `bun uds [your command name]` to test your functionality.
+Alternatively, you can use environment variables instead of flags.
 
-Commands are organized in a tree structure. The root command is the name of the CLI (uds), and then we can have subcommands under that, and subcommands under those, and so on.
+| Variable       | Description                 | Default         | Required         |
+| -------------- | --------------------------- | --------------- | ---------------- |
+| `UDS_ID`       | ID from the Configurator    |                 | <RequiredChip /> |
+| `UDS_OUT_FILE` | File to write the output to | ./uds.config.ts |                  |
 
-For example, a command structure might look like this:
+**Example:**
 
+```shell
+UDS_ID=[id] UDS_OUT_FILE=[path] uds sync
 ```
-cli/
-  commands/
-    pizza.ts        # pizza
-    help.ts         # pizza help
-    bake/
-      bake.ts       # pizza bake
-      cheese.ts     # pizza bake cheese
-      pepperoni.ts  # pizza bake pepperoni
-```
 
-## Command files
+### Purge
+
+The `uds purge` command is used to optimize and reduce the amount of CSS produced by your app.
 
-Commands are exported as defaults from each command file. They look like this:
+Running this command produces a `./dist/safelist.ts` file in the root of your project. This file imported in your `tailwind.config.js` and passed to the `safelist` configuration option.
 
 ```typescript
-import { type Props } from 'bluebun';
-
-export default {
-  name: 'bake',
-  description: 'Bake a pizza',
-  alias: ['b'],
-  run: async (props: Props) => {
-    // bake it!
-  },
+/** @type {import('tailwindcss').Config} */
+const { safelist } = require(`${__dirname}/dist/safelist.ts`);
+
+module.exports = {
+  content: ['./pages/**/*.{html,jsx,tsx}', './components/**/*.{html,jsx,tsx}'],
+  safelist,
+  // ...
 };
 ```
 
-## Command properties
-
-Commands have the following properties:
+For more information about safelisting classes in Tailwind, visit the [official documentation](https://tailwindcss.com/docs/content-configuration#safelisting-classes)
 
-- `name` - the name of the command
-- `description` - a description of the command for the automatic help system
-- `alias` - an array of aliases for the command (can also be a single string)
-- `run` - the function that is run when the command is run, usually `async`
+**Example:**
 
-## Props
-
-The `run` function is passed a `Props` object. This object contains the command path, the arguments, and the options, as well as a few other useful things.
+```shell
+uds purge
+```
 
-Here are the properties available on the `props` object if we were to run `uds bake cheese convection --sliced --temp=400 --time 30`:
+#### Enviornment variables
 
-- `name` - the name of the CLI (uds)
-- `cliPath` - the path to the CLI (./uds-cli)
-- `argv` - the raw arguments passed to the CLI (e.g. `["/bin/bun", "/bin/uds", "bake", "cheese", "convection", "--sliced", "--temp=400", "--time", "30"]`)
-- `commandPath` - the path to the command that was run (e.g. `["bake", "cheese"]`)
-- `arguments` - the positional arguments passed to the command (e.g. `["convection"]`)
-- `options` - the options passed to the command (e.g. `{ sliced: true, temp: 400, time: 30 }`)
-- `first` - the first argument passed to the command (e.g. `"convection"`)
-- `second` - the second argument passed to the command (e.g. `undefined`)
-- `third` - the third argument passed to the command (e.g. `undefined`)
+| Variable                        | Description                                 | Default | Required |
+| ------------------------------- | ------------------------------------------- | ------- | -------- |
+| `ENABLED_SCALE_AND_COLOR_MODES` | Selects which color and scale modes to keep | all     |          |
 
-Given these props, we might have a command that looks like this:
+**Example:**
 
-```typescript
-import { type Props, spinStart, spinStop } from 'bluebun';
-import { createPizza, slice } from './_pizza';
-import { convectionBake, toasterBake, regularBake } from './_bakePizza';
-
-export default {
-  name: 'bake',
-  description: 'Bake a pizza',
-  alias: ['b'],
-  run: async (props: Props) => {
-    const { first, second, third, options } = props;
-
-    const pizza = createPizza();
-
-    spinStart('Baking pizza...');
-    if (first === 'convection') {
-      await convectionBake(pizza, options.temp, options.time);
-    } else if (first === 'toaster') {
-      await toasterBake(pizza, options.temp, options.time);
-    } else {
-      await regularBake(pizza, options.temp, options.time);
-    }
-    spinStop('✅ Pizza baked!');
-
-    spinStart('Slicing pizza...');
-    if (options.sliced) {
-      await slice(pizza);
-    }
-    spinStop('✅ Pizza sliced!');
-  },
-};
+```shell
+ENABLED_SCALE_AND_COLOR_MODES="dark,large" uds purge
 ```
 
-# Reference
+### Expo (WIP)
 
-Bluebun comes with a number of built-in utilities that are useful. They're all exported from `bluebun` directly, so you can import them like this:
+The `uds expo` command is for building and launching React Native apps using Expo.
+This command is still a WIP and is only used internally at the moment.
 
-```typescript
-import { inputKey } from 'bluebun';
+```shell
+uds expo build --profile [profile] --platform [ios|android]
+uds expo dev --profile [profile] --platform [ios|android]
+uds expo launch --profile [profile] --platform [ios|android]
+uds expo update --profile [profile] --platform [ios|android]
+uds expo --help
 ```
 
-Each of the following docs has usage examples and a Testing section that gives examples on how to write tests for them.
+## Development
+
+The CLI is created with [Bluebun](https://github.com/jamonholmgren/bluebun/) (inspired by [Gluegun](https://github.com/infinitered/gluegun)), but specifically designed to be used with [Bun](https://bun.sh). Bluebun relies on Bun APIs and is designed to be extremely fast, with no-dependencies.
 
-## CLI
+### Adding a command
 
-- [run](https://github.com/jamonholmgren/bluebun/blob/main/docs/reference/run.md) - run the CLI and command
-- [cli](https://github.com/jamonholmgren/bluebun/blob/main/docs/reference/cli.md) - start the CLI without running the command
-- [commandHelp](https://github.com/jamonholmgren/bluebun/blob/main/docs/reference/commandHelp.md) - get a list of all commands and their descriptions
+Commands are organized in a tree structure in `uds/cli/commands`. The root command is the name of the CLI (`uds`) and in `uds.ts`, which subcommand being in its own file. See the Bluebun [Command docs](https://github.com/jamonholmgren/bluebun/blob/main/docs/commands.md) for more information on usage docs and creating command files.
 
-## User Interaction
+**Important note:**
 
-- [ask](https://github.com/jamonholmgren/bluebun/blob/main/docs/reference/ask.md) - ask the user a question via a prompt
-- [cursor](https://github.com/jamonholmgren/bluebun/blob/main/docs/reference/cursor.md) - manipulate the cursor
-- [inputKey](https://github.com/jamonholmgren/bluebun/blob/main/docs/reference/inputKey.md) - wait for a single keypress
-- [inputKeys](https://github.com/jamonholmgren/bluebun/blob/main/docs/reference/inputKeys.md) - wait for and handle multiple keypresses
+Adding nested commands, i.e. `uds expo dev` does work correctly when UDS is consumed from npm. As a workaround, please see code for expo/expo.ts for re-routing sub-commands from the root command file. To verify your CLI command works correctly you should run `npm pack` within the packages/uds directory. Once you have your generated tarball you should copy that tarball to a test application such as https://github.com/yahoo-design/uds-nextjs-demo, then add `"@yahoo/uds": "file:./tarball-generated-from-npm-pack.tgz` to it's dependencies and run an install. Now you should be able to run `bun uds [your command name]` to test your functionality.
 
-## Output
+### API Reference
 
-- [print](https://github.com/jamonholmgren/bluebun/blob/main/docs/reference/print.md) - print a string to the terminal
-- [spinner](https://github.com/jamonholmgren/bluebun/blob/main/docs/reference/spinner.md) - start and stop a spinner
-- [progress](https://github.com/jamonholmgren/bluebun/blob/main/docs/reference/progress.md) - start, update, and stop a progress bar
-- [styles and colors](https://github.com/jamonholmgren/bluebun/blob/main/docs/reference/styles.md) - style and colorize text
+Bluebun comes with a number of built-in utilities that are exported from the main `bluebun` package. See [reference guide](https://github.com/jamonholmgren/bluebun/blob/main/docs/reference.md) for more.

package/cli/commands/purge.ts

@@ -1,15 +1,19 @@
 import { Props, spinStart, spinStop } from 'bluebun';
 
-import { purge } from '../utils/purgeCSS';
+import { purge, PurgeOptions } from '../utils/purgeCSS';
+
+interface PurgeProps extends Props {
+  options: PurgeOptions;
+}
 
 export default {
   name: 'purge',
   description: `Purge unused CSS`,
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  run: async (props: Props) => {
+  run: async (props: PurgeProps) => {
     spinStart('Purging css...');
 
-    await purge();
+    await purge(props.options);
 
     spinStop('✅', 'Purging css done!');
   },

package/cli/env.d.ts

@@ -14,5 +14,6 @@ declare module 'bun' {
     EXPO_USE_METRO_WORKSPACE_ROOT?: string;
     EXPO_BUNDLE_APP?: string;
     ESLINT_USE_FLAT_CONFIG?: string;
+    ENABLED_SCALE_AND_COLOR_MODES?: string;
   }
 }

package/cli/preload.ts

@@ -29,4 +29,14 @@ mock.module('@yahoo/uds/tailwindPurge', () => ({
     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/purgeCSS.test.ts

@@ -1,20 +1,40 @@
+import { defaultTokensConfig } from '@yahoo/uds/tokens';
 import { describe, expect, it } from 'bun:test';
 import { Project } from 'ts-morph';
 
 import {
+  getClassesForEnabledThemesAndScales,
   getComponentsToConvertToTW,
   getFiles,
   getTailwindSafelist,
+  getUsedProps,
   isUDSComponent,
   parseFiles,
 } from './purgeCSS';
 
 const PAGE_A_CODE = `
-import { Button } from '@yahoo/uds';
+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>
   )
@@ -37,7 +57,7 @@ const PageB = () => {
 `;
 
 const FILES = ['/pages/PageA.tsx', '/pages/PageB.tsx'];
-const IMPORTED_UDS_COMPONENTS = ['Button', 'HStack', 'Spinner'];
+const IMPORTED_UDS_COMPONENTS = ['HStack', 'Button', 'Spinner'];
 
 describe('purgeCSS', () => {
   const project = new Project();
@@ -67,11 +87,31 @@ describe('purgeCSS', () => {
 
   describe('getTailwindSafelist', () => {
     it('returns the tailwind classes corresponding to the props on a component', () => {
-      const res = getTailwindSafelist(IMPORTED_UDS_COMPONENTS);
-
-      expect(res).toEqual(
-        'text-accent text-alert text-black text-brand text-positive text-warning text-white items-start items-end items-center items-stretch items-baseline justify-start justify-end justify-center justify-between justify-around justify-evenly ',
-      );
+      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',
+      ]);
     });
   });
 
@@ -85,7 +125,7 @@ describe('purgeCSS', () => {
 
   describe('isUDSComponent', () => {
     it('returns true if the component is exported from UDS', () => {
-      const res = isUDSComponent('Button');
+      const res = isUDSComponent('HStack');
 
       expect(res).toBeTrue();
     });
@@ -96,4 +136,44 @@ describe('purgeCSS', () => {
       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',
+      ]);
+    });
+  });
+
+  describe('getClassesForEnabledThemesAndScales', () => {
+    it('returns the list of classes related to the mode/themes we have in the config', () => {
+      const classes = getClassesForEnabledThemesAndScales(defaultTokensConfig);
+
+      expect(classes).toEqual([
+        'uds-color-mode-light',
+        'uds-color-mode-dark',
+        'uds-scale-mode-xsmall',
+        'uds-scale-mode-small',
+        'uds-scale-mode-medium',
+        'uds-scale-mode-large',
+        'uds-scale-mode-xlarge',
+        'uds-scale-mode-xxlarge',
+        'uds-scale-mode-xxxlarge',
+      ]);
+    });
+  });
 });