@blueprintjs/icons 4.0.0-beta.4 → 4.0.0-beta.8

package/src/iconCodepoints.ts

@@ -14,5 +14,23 @@
  * limitations under the License.
  */
 
+import { BLUEPRINT_ICONS_16_CODEPOINTS } from "./generated/16px/blueprint-icons-16";
+import type { IconName } from "./iconNames";
 // icon sets are identical aside from SVG paths, so we just import the info for the 16px set
-export { BLUEPRINT_ICONS_16_CODEPOINTS as IconCodepoints } from "./generated/16px/blueprint-icons-16";
+
+/**
+ * Icon codepoints as base 10 number strings. If you need to render these strings
+ * into an SVG document or as `::before` pseudo content, consider using `getIconContentString()`
+ * instead.
+ */
+export const IconCodepoints = BLUEPRINT_ICONS_16_CODEPOINTS;
+
+/**
+ * Returns the hex code content string which represents the codepoint in the icon font
+ * for a given icon. You can render this string to the DOM and if the icon font is loaded
+ * as an active font family, this string will be replaced with the associated icon.
+ */
+export function getIconContentString(icon: IconName) {
+    // parse base 10 number from string, then convert to hex code
+    return String.fromCodePoint(parseInt(IconCodepoints[icon], 10));
+}

package/src/iconNames.ts

@@ -16,53 +16,24 @@
 
 /* eslint-disable camelcase */
 
-import { snakeCase } from "change-case";
+import { pascalCase, snakeCase } from "change-case";
+
+import { BlueprintIcons_16, BlueprintIcons_16Id as IconName } from "./generated/16px/blueprint-icons-16";
+import type { PascalCase, ScreamingSnakeCase } from "./type-utils";
 
 // icon sets are identical aside from SVG paths, so we just import the info for the 16px set
-import {
-    BlueprintIcons_16,
-    BlueprintIcons_16Id as IconName,
-    BlueprintIcons_16Key,
-} from "./generated/16px/blueprint-icons-16";
 
 export type { IconName };
 
-const IconNamesLegacy: Record<string, IconName> = {};
+const IconNamesNew = {} as Record<PascalCase<IconName>, IconName>;
+const IconNamesLegacy = {} as Record<ScreamingSnakeCase<IconName>, IconName>;
 
-for (const [pascalCaseKey, iconName] of Object.entries(BlueprintIcons_16)) {
-    const screamingSnakeCaseKey = snakeCase(pascalCaseKey).toUpperCase();
-    IconNamesLegacy[screamingSnakeCaseKey] = iconName;
+for (const name of Object.values(BlueprintIcons_16) as IconName[]) {
+    IconNamesNew[pascalCase(name) as PascalCase<IconName>] = name;
+    IconNamesLegacy[snakeCase(name).toUpperCase() as ScreamingSnakeCase<IconName>] = name;
 }
 
 export const IconNames = {
-    ...BlueprintIcons_16,
-    ...(IconNamesLegacy as Record<ScreamingSnakeCaseIconNames, IconName>),
+    ...IconNamesNew,
+    ...IconNamesLegacy,
 };
-
-type ScreamingSnakeCaseIconNames = Uppercase<StripLeadingUnderscore<CamelToSnake<BlueprintIcons_16Key>>>;
-
-/**
- * The CamelToSnake converter works ok for PascalCase identifiers, but it
- * always adds a leading underscore. So we add this simple additional converter
- * to the chain to strip that underscore.
- */
-type StripLeadingUnderscore<T extends string> = T extends `_${infer R}` ? `${R}` : T;
-
-/**
- * This is a hacky implementation of a camelCase to Snake_Case string literal
- * type converter... it works up to 30 characters, which is fine for our
- * current icon set.
- *
- * Copied from StackOverflow
- *
- * @see https://stackoverflow.com/questions/64932525/is-it-possible-to-use-mapped-types-in-typescript-to-change-a-types-key-names
- */
-type CamelToSnake<T extends string> = string extends T
-    ? string
-    : T extends `${infer C0}${infer C1}${infer R}`
-    ? `${C0 extends Uppercase<C0> ? "_" : ""}${Lowercase<C0>}${C1 extends Uppercase<C1>
-          ? "_"
-          : ""}${Lowercase<C1>}${CamelToSnake<R>}`
-    : T extends `${infer C0}${infer R}`
-    ? `${C0 extends Uppercase<C0> ? "_" : ""}${Lowercase<C0>}${CamelToSnake<R>}`
-    : "";

package/src/iconSvgPaths.ts

@@ -14,41 +14,19 @@
  * limitations under the License.
  */
 
+import { pascalCase } from "change-case";
+
 import * as IconSvgPaths16 from "./generated/16px/paths";
 import * as IconSvgPaths20 from "./generated/20px/paths";
 import type { IconName } from "./iconNames";
+import type { PascalCase } from "./type-utils";
 
 export { IconSvgPaths16, IconSvgPaths20 };
 
 /**
- * Type safe string literal conversion of snake-case icon names to camelCase icon names,
+ * Type safe string literal conversion of snake-case icon names to PascalCase icon names,
  * useful for indexing into the SVG paths record to extract a single icon's SVG path definition.
- *
- * N.B. `IconSvgPaths16` and `IconSvgPaths20` are assignable to each other, so it doesn't matter
- * which one is used in the return type definition here.
  */
-export function iconNameToPathsRecordKey(name: IconName): keyof typeof IconSvgPaths16 {
-    return kebabCaseToCamelCase(name);
+export function iconNameToPathsRecordKey(name: IconName): PascalCase<IconName> {
+    return pascalCase(name) as PascalCase<IconName>;
 }
-
-/**
- * Type safe string literal conversion of snake-case strings to camelCase strings.
- * Note that this requires TypeScript 4.1+.
- *
- * Implementation and template literal mapped types borrowed from
- * https://davidtimms.github.io/programming-languages/typescript/2020/11/20/exploring-template-literal-types-in-typescript-4.1.html
- */
-function kebabCaseToCamelCase<S extends string>(snakeCaseString: S): KebabCaseToCamelCase<S> {
-    return snakeCaseString
-        .split("-")
-        .map((word, i) => (i === 0 ? word.toLowerCase() : word && word[0].toUpperCase() + word.slice(1).toLowerCase()))
-        .join("") as KebabCaseToCamelCase<S>;
-}
-
-type KebabCaseToCamelCase<S extends string> = S extends `${infer FirstWord}-${infer Rest}`
-    ? `${Lowercase<FirstWord>}${KebabCaseToPascalCase<Rest>}`
-    : `${Lowercase<S>}`;
-
-type KebabCaseToPascalCase<S extends string> = S extends `${infer FirstWord}-${infer Rest}`
-    ? `${Capitalize<Lowercase<FirstWord>>}${KebabCaseToPascalCase<Rest>}`
-    : Capitalize<Lowercase<S>>;

package/src/index.ts

@@ -15,5 +15,5 @@
  */
 
 export { IconSvgPaths16, IconSvgPaths20, iconNameToPathsRecordKey } from "./iconSvgPaths";
-export { IconCodepoints } from "./iconCodepoints";
+export { getIconContentString, IconCodepoints } from "./iconCodepoints";
 export { IconName, IconNames } from "./iconNames";

package/src/type-utils/camel-case.ts

@@ -0,0 +1,80 @@
+import { WordSeparators } from "./sourceUtilities";
+import { Split } from "./utilities";
+
+/**
+Step by step takes the first item in an array literal, formats it and adds it to a string literal, and then recursively appends the remainder.
+
+Only to be used by `CamelCaseStringArray<>`.
+
+@see CamelCaseStringArray
+*/
+type InnerCamelCaseStringArray<Parts extends any[], PreviousPart> = Parts extends [
+    `${infer FirstPart}`,
+    ...infer RemainingParts
+]
+    ? FirstPart extends undefined
+        ? ""
+        : FirstPart extends ""
+        ? InnerCamelCaseStringArray<RemainingParts, PreviousPart>
+        : `${PreviousPart extends "" ? FirstPart : Capitalize<FirstPart>}${InnerCamelCaseStringArray<
+              RemainingParts,
+              FirstPart
+          >}`
+    : "";
+
+/**
+Starts fusing the output of `Split<>`, an array literal of strings, into a camel-cased string literal.
+
+It's separate from `InnerCamelCaseStringArray<>` to keep a clean API outwards to the rest of the code.
+
+@see Split
+*/
+type CamelCaseStringArray<Parts extends string[]> = Parts extends [`${infer FirstPart}`, ...infer RemainingParts]
+    ? Uncapitalize<`${FirstPart}${InnerCamelCaseStringArray<RemainingParts, FirstPart>}`>
+    : never;
+
+/**
+Convert a string literal to camel-case.
+
+This can be useful when, for example, converting some kebab-cased command-line flags or a snake-cased database result.
+
+@example
+```
+import {CamelCase} from 'type-fest';
+
+// Simple
+
+const someVariable: CamelCase<'foo-bar'> = 'fooBar';
+
+// Advanced
+
+type CamelCasedProperties<T> = {
+	[K in keyof T as CamelCase<K>]: T[K]
+};
+
+interface RawOptions {
+	'dry-run': boolean;
+	'full_family_name': string;
+	foo: number;
+	BAR: string;
+	QUZ_QUX: number;
+	'OTHER-FIELD': boolean;
+}
+
+const dbResult: CamelCasedProperties<ModelProps> = {
+	dryRun: true,
+	fullFamilyName: 'bar.js',
+	foo: 123,
+	bar: 'foo',
+	quzQux: 6,
+	otherField: false
+};
+```
+
+@category Template Literals
+*/
+export type CamelCase<K> = K extends string
+    ? K extends Uppercase<K>
+        ? CamelCaseStringArray<Split<Lowercase<K>, WordSeparators>>
+        : CamelCaseStringArray<Split<K, WordSeparators>>
+    : K;

package/src/type-utils/delimiter-case.ts

@@ -0,0 +1,105 @@
+import { UpperCaseCharacters, WordSeparators } from "./sourceUtilities";
+
+/**
+Unlike a simpler split, this one includes the delimiter splitted on in the resulting array literal. This is to enable splitting on, for example, upper-case characters.
+
+@category Template Literals
+*/
+export type SplitIncludingDelimiters<Source extends string, Delimiter extends string> = Source extends ""
+    ? []
+    : Source extends `${infer FirstPart}${Delimiter}${infer SecondPart}`
+    ? Source extends `${FirstPart}${infer UsedDelimiter}${SecondPart}`
+        ? UsedDelimiter extends Delimiter
+            ? Source extends `${infer FirstPart}${UsedDelimiter}${infer SecondPart}`
+                ? [
+                      ...SplitIncludingDelimiters<FirstPart, Delimiter>,
+                      UsedDelimiter,
+                      ...SplitIncludingDelimiters<SecondPart, Delimiter>
+                  ]
+                : never
+            : never
+        : never
+    : [Source];
+
+/**
+Format a specific part of the splitted string literal that `StringArrayToDelimiterCase<>` fuses together, ensuring desired casing.
+
+@see StringArrayToDelimiterCase
+*/
+type StringPartToDelimiterCase<
+    StringPart extends string,
+    UsedWordSeparators extends string,
+    UsedUpperCaseCharacters extends string,
+    Delimiter extends string
+> = StringPart extends UsedWordSeparators
+    ? Delimiter
+    : StringPart extends UsedUpperCaseCharacters
+    ? `${Delimiter}${Lowercase<StringPart>}`
+    : StringPart;
+
+/**
+Takes the result of a splitted string literal and recursively concatenates it together into the desired casing.
+
+It receives `UsedWordSeparators` and `UsedUpperCaseCharacters` as input to ensure it's fully encapsulated.
+
+@see SplitIncludingDelimiters
+*/
+type StringArrayToDelimiterCase<
+    Parts extends any[],
+    UsedWordSeparators extends string,
+    UsedUpperCaseCharacters extends string,
+    Delimiter extends string
+> = Parts extends [`${infer FirstPart}`, ...infer RemainingParts]
+    ? `${StringPartToDelimiterCase<
+          FirstPart,
+          UsedWordSeparators,
+          UsedUpperCaseCharacters,
+          Delimiter
+      >}${StringArrayToDelimiterCase<RemainingParts, UsedWordSeparators, UsedUpperCaseCharacters, Delimiter>}`
+    : "";
+
+/**
+Convert a string literal to a custom string delimiter casing.
+
+This can be useful when, for example, converting a camel-cased object property to an oddly cased one.
+
+@see KebabCase
+@see SnakeCase
+
+@example
+```
+import {DelimiterCase} from 'type-fest';
+
+// Simple
+
+const someVariable: DelimiterCase<'fooBar', '#'> = 'foo#bar';
+
+// Advanced
+
+type OddlyCasedProperties<T> = {
+	[K in keyof T as DelimiterCase<K, '#'>]: T[K]
+};
+
+interface SomeOptions {
+	dryRun: boolean;
+	includeFile: string;
+	foo: number;
+}
+
+const rawCliOptions: OddlyCasedProperties<SomeOptions> = {
+	'dry#run': true,
+	'include#file': 'bar.js',
+	foo: 123
+};
+```
+
+@category Template Literals
+*/
+export type DelimiterCase<Value, Delimiter extends string> = Value extends string
+    ? StringArrayToDelimiterCase<
+          SplitIncludingDelimiters<Value, WordSeparators | UpperCaseCharacters>,
+          WordSeparators,
+          UpperCaseCharacters,
+          Delimiter
+      >
+    : Value;

package/src/type-utils/includes.ts

@@ -0,0 +1,26 @@
+/**
+Returns a boolean for whether given two types are equal.
+
+@link https://github.com/microsoft/TypeScript/issues/27024#issuecomment-421529650
+*/
+type IsEqual<T, U> = (<G>() => G extends T ? 1 : 2) extends <G>() => G extends U ? 1 : 2 ? true : false;
+
+/**
+Returns a boolean for whether the given array includes the given item.
+
+This can be useful if another type wants to make a decision based on whether the array includes that item.
+
+@example
+```
+import {Includes} from 'type-fest';
+
+type hasRed<array extends any[]> = Includes<array, 'red'>;
+```
+
+@category Utilities
+*/
+export type Includes<Value extends any[], Item> = IsEqual<Value[0], Item> extends true
+    ? true
+    : Value extends [Value[0], ...infer rest]
+    ? Includes<rest, Item>
+    : false;

package/src/type-utils/index.ts

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2021 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/** @fileoverview Mapped type utils copied from the "type-fest" package */
+
+export { PascalCase } from "./pascal-case";
+export { ScreamingSnakeCase } from "./screaming-snake-case";

package/src/type-utils/pascal-case.ts

@@ -0,0 +1,35 @@
+import { CamelCase } from "./camel-case";
+
+/**
+Converts a string literal to pascal-case.
+
+@example
+```
+import {PascalCase} from 'type-fest';
+
+// Simple
+
+const someVariable: PascalCase<'foo-bar'> = 'FooBar';
+
+// Advanced
+
+type PascalCaseProps<T> = {
+	[K in keyof T as PascalCase<K>]: T[K]
+};
+
+interface RawOptions {
+	'dry-run': boolean;
+	'full_family_name': string;
+	foo: number;
+}
+
+const dbResult: CamelCasedProperties<ModelProps> = {
+	DryRun: true,
+	FullFamilyName: 'bar.js',
+	Foo: 123
+};
+```
+
+@category Template Literals
+*/
+export type PascalCase<Value> = CamelCase<Value> extends string ? Capitalize<CamelCase<Value>> : CamelCase<Value>;

package/src/type-utils/screaming-snake-case.ts

@@ -0,0 +1,32 @@
+import { SplitIncludingDelimiters } from "./delimiter-case";
+import { SnakeCase } from "./snake-case";
+import { Includes } from "./includes";
+
+/**
+Returns a boolean for whether the string is screaming snake case.
+*/
+type IsScreamingSnakeCase<Value extends string> = Value extends Uppercase<Value>
+    ? Includes<SplitIncludingDelimiters<Lowercase<Value>, "_">, "_"> extends true
+        ? true
+        : false
+    : false;
+
+/**
+Convert a string literal to screaming-snake-case.
+
+This can be useful when, for example, converting a camel-cased object property to a screaming-snake-cased SQL column name.
+
+@example
+```
+import {ScreamingSnakeCase} from 'type-fest';
+
+const someVariable: ScreamingSnakeCase<'fooBar'> = 'FOO_BAR';
+```
+
+@category Template Literals
+*/
+export type ScreamingSnakeCase<Value> = Value extends string
+    ? IsScreamingSnakeCase<Value> extends true
+        ? Value
+        : Uppercase<SnakeCase<Value>>
+    : Value;

package/src/type-utils/snake-case.ts

@@ -0,0 +1,37 @@
+import { DelimiterCase } from "./delimiter-case";
+
+/**
+Convert a string literal to snake-case.
+
+This can be useful when, for example, converting a camel-cased object property to a snake-cased SQL column name.
+
+@example
+```
+import {SnakeCase} from 'type-fest';
+
+// Simple
+
+const someVariable: SnakeCase<'fooBar'> = 'foo_bar';
+
+// Advanced
+
+type SnakeCasedProperties<T> = {
+	[K in keyof T as SnakeCase<K>]: T[K]
+};
+
+interface ModelProps {
+	isHappy: boolean;
+	fullFamilyName: string;
+	foo: number;
+}
+
+const dbResult: SnakeCasedProperties<ModelProps> = {
+	'is_happy': true,
+	'full_family_name': 'Carla Smith',
+	foo: 123
+};
+```
+
+@category Template Literals
+*/
+export type SnakeCase<Value> = DelimiterCase<Value, "_">;

package/src/type-utils/sourceUtilities.ts

@@ -0,0 +1,31 @@
+export type UpperCaseCharacters =
+    | "A"
+    | "B"
+    | "C"
+    | "D"
+    | "E"
+    | "F"
+    | "G"
+    | "H"
+    | "I"
+    | "J"
+    | "K"
+    | "L"
+    | "M"
+    | "N"
+    | "O"
+    | "P"
+    | "Q"
+    | "R"
+    | "S"
+    | "T"
+    | "U"
+    | "V"
+    | "W"
+    | "X"
+    | "Y"
+    | "Z";
+
+export type WordSeparators = "-" | "_" | " ";
+
+export type StringDigit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";

package/src/type-utils/utilities.ts

@@ -0,0 +1,10 @@
+/**
+Recursively split a string literal into two parts on the first occurence of the given string, returning an array literal of all the separate parts.
+*/
+export type Split<S extends string, D extends string> = string extends S
+    ? string[]
+    : S extends ""
+    ? []
+    : S extends `${infer T}${D}${infer U}`
+    ? [T, ...Split<U, D>]
+    : [S];