feat: 🎸 Custom UI Boiler Plate Code

lib/ts/config.ts

@@ -1,4 +1,5 @@
-import { Answers, QuestionOption, RecipeQuestionOption, UserFlags } from "./types.js";
+import { Answers, QuestionOption, RecipeQuestionOption, UIBuildType, UIBuildTypeOption, UserFlags } from "./types.js";
+import { FILTER_CHOICES_STRATEGY, filterChoices } from "./filterChoicesUtils.js";
 import { validateFolderName } from "./userArgumentUtils.js";
 import {
     getDjangoPythonRunScripts,
@@ -467,6 +468,17 @@ export const recipeOptions: RecipeQuestionOption[] = [
     },
 ];
 
+export const uiBuildOptions: UIBuildTypeOption[] = [
+    {
+        value: UIBuildType.PRE_BUILT,
+        displayName: "Pre-built UI (Recommended)",
+    },
+    {
+        value: UIBuildType.CUSTOM,
+        displayName: "Custom UI",
+    },
+];
+
 /**
  * Export for all the questions to ask the user, should follow the exact format mentioned here https://github.com/SBoudrias/Inquirer.js#objects because this config is passed to inquirer. The order of questions depends on the position of the object in the array
  */
@@ -496,11 +508,29 @@ export async function getQuestions(flags: UserFlags) {
                 return "Invalid project name: " + validations.problems![0];
             },
         },
+        {
+            name: "ui",
+            type: "list",
+            message: "Choose the ui built type for your frontend:",
+            choices: mapOptionsToChoices(uiBuildOptions),
+            when: (answers: Answers) => {
+                if (flags.ui) {
+                    answers.ui = flags.ui;
+                    return false;
+                }
+                return true;
+            },
+        },
         {
             name: "frontend",
             type: "list",
             message: "Choose a frontend framework (Visit our documentation for integration with other frameworks):",
-            choices: mapOptionsToChoices(await getFrontendOptions(flags)),
+            choices: async (answers: Answers) =>
+                filterChoices(
+                    mapOptionsToChoices(await getFrontendOptions(flags)),
+                    answers,
+                    FILTER_CHOICES_STRATEGY.filterFrontendByUiType
+                ),
             when: flags.frontend === undefined,
         },
         {
@@ -555,7 +585,12 @@ export async function getQuestions(flags: UserFlags) {
             name: "recipe",
             type: "list",
             message: "What type of authentication do you want to use?",
-            choices: mapOptionsToChoices(recipeOptions),
+            choices: async (answers: Answers) =>
+                filterChoices(
+                    mapOptionsToChoices(recipeOptions),
+                    answers,
+                    FILTER_CHOICES_STRATEGY.filterRecipeByUiType
+                ),
             when: (answers: Answers) => {
                 // For capacitor we don't ask this question because it has its own way of swapping between recipes
                 if (answers.frontend === "capacitor") {

lib/ts/filterChoicesUtils.ts

@@ -0,0 +1,111 @@
+import { Answers, IPromptFilterStrategy, PromptListChoice, UIBuildType, UserFlagsRaw } from "./types.js";
+
+const getIsValueSupported = (value: string, supportedValues: string[]) => {
+    return supportedValues.includes(value);
+};
+
+const filterFrontendByUiType: IPromptFilterStrategy = {
+    validValues: ["react"],
+    filterChoices(choices, answers) {
+        if (answers.ui === UIBuildType.PRE_BUILT) {
+            return choices;
+        }
+        return choices.filter((choice) => getIsValueSupported(choice.value, this.validValues));
+    },
+    validateUserArguments(userArguments) {
+        if (!userArguments.frontend) return true;
+        return (
+            userArguments.ui === UIBuildType.PRE_BUILT || getIsValueSupported(userArguments.frontend, this.validValues)
+        );
+    },
+};
+
+const filterRecipeByUiType: IPromptFilterStrategy = {
+    validValues: ["emailpassword", "thirdpartyemailpassword"],
+    filterChoices(choices, answers) {
+        if (answers.ui === UIBuildType.PRE_BUILT) {
+            return choices;
+        }
+        return choices.filter((choice) => getIsValueSupported(choice.value, this.validValues));
+    },
+    validateUserArguments(userArguments) {
+        if (!userArguments.recipe) return true;
+        return (
+            userArguments.ui === UIBuildType.PRE_BUILT || getIsValueSupported(userArguments.recipe, this.validValues)
+        );
+    },
+};
+
+export const FILTER_CHOICES_STRATEGY = {
+    filterFrontendByUiType,
+    filterRecipeByUiType,
+};
+
+/**
+ * Filters a list of choices based on the provided strategy or strategies.
+ *
+ * @param choices - An array of `PromptListChoice` objects or a promise that resolves to such an array.
+ * @param answers - An object containing the answers to previous prompts.
+ * @param strategy - An optional filtering strategy or an array of strategies. This can be one of the predefined
+ *                   `FILTER_CHOICES_STRATEGY` values, an array of such values, or a custom function that takes an
+ *                   array of choices and returns a promise that resolves to a filtered array of choices.
+ * @returns A promise that resolves to the filtered array of `PromptListChoice` objects.
+ */
+export const filterChoices = async (
+    choices: PromptListChoice[] | Promise<PromptListChoice[]>,
+    answers: Answers,
+    strategy?:
+        | IPromptFilterStrategy
+        | IPromptFilterStrategy[]
+        | ((choices: PromptListChoice[]) => Promise<PromptListChoice[]>)
+): Promise<PromptListChoice[]> => {
+    if (choices instanceof Promise) {
+        choices = await choices;
+    }
+    if (!strategy || (Array.isArray(strategy) && strategy.length === 0)) {
+        return choices;
+    }
+    if (typeof strategy === "function") {
+        return strategy(choices);
+    }
+    if (!Array.isArray(strategy)) {
+        strategy = [strategy];
+    }
+    for (const filter of strategy) {
+        choices = filter.filterChoices(choices, answers);
+    }
+    return choices;
+};
+
+export const validateUserArgumentsByFilterStrategy = (
+    userArguments: UserFlagsRaw,
+    argumentToValidateKey: keyof UserFlagsRaw,
+    strategy?: IPromptFilterStrategy | IPromptFilterStrategy[]
+): boolean => {
+    if (!strategy) {
+        return true;
+    }
+    if (!Array.isArray(strategy)) {
+        strategy = [strategy];
+    }
+    if (!userArguments?.[argumentToValidateKey]) {
+        throw new Error(`Invalid ${argumentToValidateKey} provided`);
+    }
+
+    for (const filter of strategy) {
+        if (!filter.validateUserArguments(userArguments)) {
+            return false;
+        }
+    }
+    return true;
+};
+
+export const isValidUiBasedOnFilters = (userArguments: UserFlagsRaw): boolean => {
+    if (!userArguments.ui) return true;
+    if (!Object.values(UIBuildType).includes(userArguments.ui)) return false;
+    if (userArguments.ui === UIBuildType.PRE_BUILT) return true;
+    return validateUserArgumentsByFilterStrategy(userArguments, "ui", [
+        FILTER_CHOICES_STRATEGY.filterFrontendByUiType,
+        FILTER_CHOICES_STRATEGY.filterRecipeByUiType,
+    ]);
+};

lib/ts/types.ts

@@ -192,7 +192,10 @@ export type RecipeQuestionOption = {
     shouldDisplay?: boolean;
 };
 
+export type UIBuildTypeOption = RecipeQuestionOption;
+
 export type Answers = {
+    ui: UIBuildType;
     frontend?: SupportedFrontends;
     backend?: SupportedBackends;
     recipe: string;
@@ -216,6 +219,11 @@ export type SupportedPackageManagers = "npm" | "yarn" | "pnpm" | "bun";
 
 export const allPackageManagers: SupportedPackageManagers[] = ["npm", "yarn", "pnpm", "bun"];
 
+export enum UIBuildType {
+    CUSTOM = "custom",
+    PRE_BUILT = "pre-built",
+}
+
 export function isValidPackageManager(manager: string): manager is SupportedPackageManagers {
     if (allPackageManagers.includes(manager as SupportedPackageManagers)) {
         return true;
@@ -232,6 +240,7 @@ export type UserFlagsRaw = {
     frontend?: SupportedFrontends;
     backend?: SupportedBackends;
     manager?: SupportedPackageManagers;
+    ui?: UIBuildType;
     autostart?: string | boolean;
 };
 
@@ -268,3 +277,19 @@ export type AnalyticsEventWithCommonProperties = AnalyticsEvent & {
     os: string;
     cliversion: string;
 };
+
+export type PromptListChoice = {
+    name: string;
+    value: string;
+};
+
+export const isValidUIBuildType = (userArguments: UserFlagsRaw): boolean => {
+    if (!userArguments.ui) return true;
+    return Object.values(UIBuildType).includes(userArguments.ui);
+};
+
+export interface IPromptFilterStrategy {
+    validValues: string[];
+    filterChoices: (choices: PromptListChoice[], answers: Answers) => PromptListChoice[];
+    validateUserArguments: (userArguments: UserFlagsRaw) => boolean;
+}

lib/ts/userArgumentUtils.ts

@@ -8,11 +8,14 @@ import {
     isValidFrontend,
     isValidPackageManager,
     isValidRecipeName,
+    isValidUIBuildType,
+    UIBuildType,
     UserFlags,
     UserFlagsRaw,
 } from "./types.js";
 import validateProjectName from "validate-npm-package-name";
 import path from "path";
+import { isValidUiBasedOnFilters } from "./filterChoicesUtils.js";
 
 export function validateNpmName(name: string): {
     valid: boolean;
@@ -78,6 +81,18 @@ export function validateUserArguments(userArguments: UserFlagsRaw) {
             throw new Error("Invalid package manager provided, valid values:\n" + availableManagers);
         }
     }
+
+    if (userArguments.ui !== undefined) {
+        if (!isValidUIBuildType(userArguments)) {
+            throw new Error(
+                `Invalid argument for ui provided. Supported arguments are ${Object.values(UIBuildType).join(", ")}`
+            );
+        }
+
+        if (!isValidUiBasedOnFilters(userArguments)) {
+            throw new Error(`UI type ${userArguments.ui} is not supported for the selected frontend or recipe.`);
+        }
+    }
 }
 
 export function modifyAnswersBasedOnSelection(answers: Answers): Answers {
@@ -113,6 +128,10 @@ export function modifyAnswersBasedOnFlags(answers: Answers, userArguments: UserF
         _answers.recipe = userArguments.recipe;
     }
 
+    if (userArguments.ui !== undefined) {
+        _answers.ui = userArguments.ui;
+    }
+
     if (userArguments.frontend !== undefined) {
         const selectedFrontend = allFrontends.filter((i) => userArguments.frontend === i.id);