Enhance Color types (#2362)

* Update .gitignore

* deprecate Mode in favor of Theme

* creates Recursive Record type

* Semantics of Color token segment types. Add TSDoc

* changesets

* Update pretty-paws-try.md

.changeset/flat-knives-hammer.md

@@ -0,0 +1,5 @@
+---
+'@leafygreen-ui/lib': minor
+---
+
+Adds `RecursiveRecord` type

.changeset/pretty-paws-try.md

@@ -0,0 +1,7 @@
+---
+'@leafygreen-ui/tokens': minor
+---
+
+- Improves semantics of color token segment type names (e.g. `Type` -> `Property`, `State` -> `InteractionState`).
+- Adds TSDoc to color types
+- Deprecates `Mode` enum in favor if `Theme` (exported from `lib`)

.gitignore

@@ -56,3 +56,6 @@ scripts/tmp.*.ts
 .changeset/pre.json
 
 TODO.md
+
+# PR train config (https://github.com/realyze/pr-train)
+.pr-train.yml

packages/lib/src/index.ts

@@ -7,7 +7,7 @@ import getTheme from './getTheme';
 export * from './helpers';
 export { validateChildren, isComponentType } from './validateChildren';
 export { createSyntheticEvent } from './createSyntheticEvent';
-export { type Mutable } from './types';
+export type { Mutable, RecursiveRecord } from './types';
 
 export { typeIs, createUniqueClassName, getNodeTextContent, getTheme, Theme };
 export type { DarkModeProps, LgIdProps };

packages/lib/src/types/RecursiveRecord.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Create a recursive Record type of any number of key sets.
+ *
+ * The second parameter (`Strict`) determines whether each union of Keys
+ * must be complete in each recursive `Record`
+ * Passing `false` to this parameter will wrap each recursive `Record` in `Partial`,
+ * resulting in a looser Record definition.
+ *
+ * E.g.
+ * ```ts
+ * ColorRecord = RecursiveRecord<
+ *   [Theme, Property, Variant, State, string],
+ *   false
+ * > =
+ * Partial<Record<Theme,
+ *   Partial<Record<Property,
+ *     Partial<Record<Variant,
+ *       Partial<Record<State, string>>
+ *     >>
+ *   >>
+ * >>
+ * ```
+ * */
+export type RecursiveRecord<
+  Keys extends Array<any>,
+  Strict extends boolean = true,
+> = Keys extends [
+  infer Key, // the current union of keys
+  ...infer Rest,
+]
+  ? Strict extends true
+    ? Record<Key & string, RecursiveRecord<Rest, Strict>>
+    : Partial<Record<Key & string, RecursiveRecord<Rest, Strict>>>
+  : Keys;

packages/lib/src/types/index.ts

@@ -1 +1,2 @@
-export { type Mutable } from './Mutable';
+export type { Mutable } from './Mutable';
+export type { RecursiveRecord } from './RecursiveRecord';

packages/tokens/src/color/color.ts

@@ -1,10 +1,10 @@
-import { Mode } from '../mode';
+import { Theme } from '@leafygreen-ui/lib';
 
-import { ModeColorRecord } from './color.types';
+import { PropertyColorRecord } from './color.types';
 import { darkModeColors } from './darkModeColors';
 import { lightModeColors } from './lightModeColors';
 
 export const color = {
-  [Mode.Dark]: darkModeColors,
-  [Mode.Light]: lightModeColors,
-} as const satisfies Record<Mode, ModeColorRecord>;
+  [Theme.Dark]: darkModeColors,
+  [Theme.Light]: lightModeColors,
+} as const satisfies Record<Theme, PropertyColorRecord>;

packages/tokens/src/color/color.types.ts

@@ -1,11 +1,17 @@
-const Type = {
+/**
+ * The element property a color token applies to
+ */
+const Property = {
   Background: 'background',
   Border: 'border',
   Icon: 'icon',
   Text: 'text',
 } as const;
-type Type = (typeof Type)[keyof typeof Type];
+type Property = (typeof Property)[keyof typeof Property];
 
+/**
+ * The context variant in which a color token should be applied
+ */
 const Variant = {
   Disabled: 'disabled',
   Placeholder: 'placeholder',
@@ -21,16 +27,29 @@ const Variant = {
 } as const;
 type Variant = (typeof Variant)[keyof typeof Variant];
 
-const State = {
+/**
+ * The interaction state in which a color token should be applied
+ */
+const InteractionState = {
   Default: 'default',
   Hover: 'hover',
   Focus: 'focus',
 } as const;
-type State = (typeof State)[keyof typeof State];
+type InteractionState =
+  (typeof InteractionState)[keyof typeof InteractionState];
 
+/**
+ * A partial Record,
+ * mapping a subset of {@link Variant} keys
+ * to a Record of {@link InteractionState} color tokens
+ */
 export type VariantColorRecord = Partial<
-  Record<Variant, Record<State, string>>
+  Record<Variant, Record<InteractionState, string>>
 >;
-export type ModeColorRecord = Record<Type, VariantColorRecord>;
 
-export { State, Type, Variant };
+/**
+ * A Record mapping {@link Property} keys to {@link VariantColorRecord}
+ */
+export type PropertyColorRecord = Record<Property, VariantColorRecord>;
+
+export { InteractionState, Property, Variant };