@headless-adminapp/app 0.0.8-0.0.9-alpha.1.0

package/src/builders/SchemaExperienceBuilder.ts

@@ -0,0 +1,488 @@
+import {
+  AsyncForm,
+  AsyncQuickCreateForm,
+  EntityMainFormCommandItemExperience,
+  Form,
+  FormExperience,
+  QuickCreateForm,
+} from '@headless-adminapp/core/experience/form';
+import { SchemaExperience } from '@headless-adminapp/core/experience/schema';
+import {
+  AsyncView,
+  EntityMainGridCommandItemExperience,
+  SubGridCommandItemExperience,
+  View,
+  ViewExperience,
+} from '@headless-adminapp/core/experience/view';
+import { Schema, SchemaAttributes } from '@headless-adminapp/core/schema';
+import { Localized } from '@headless-adminapp/core/types';
+
+abstract class BaseSchemaExperienceBuilder<S extends SchemaAttributes> {
+  protected views: View<S>[] = [];
+  protected forms: Form<S>[] = [];
+  protected lookups: View<S>[] = [];
+  protected quickCreateForms: QuickCreateForm<S>[] = [];
+
+  protected defaultViewId: string | null = null;
+  protected defaultFormId: string | null = null;
+  protected defaultLookupId: string | null = null;
+  protected defaultQuickCreateFormId: string | null = null;
+  protected locked: boolean = false;
+
+  constructor(protected readonly logicalName: string) {}
+
+  public reset() {
+    this.views = [];
+    this.forms = [];
+    this.lookups = [];
+    this.quickCreateForms = [];
+    this.defaultViewId = null;
+    this.defaultFormId = null;
+    this.defaultLookupId = null;
+    this.defaultQuickCreateFormId = null;
+    this.locked = false;
+    return this;
+  }
+
+  protected baseBuild() {
+    if (!this.defaultViewId) {
+      throw new Error('Default view is required');
+    }
+
+    if (!this.defaultFormId) {
+      throw new Error('Default form is required');
+    }
+
+    if (!this.defaultLookupId) {
+      throw new Error('Default lookup is required');
+    }
+
+    if (!this.views.find((v) => v.id === this.defaultViewId)) {
+      throw new Error('Default view not found');
+    }
+
+    if (!this.forms.find((f) => f.id === this.defaultFormId)) {
+      throw new Error('Default form not found');
+    }
+
+    if (!this.lookups.find((l) => l.id === this.defaultLookupId)) {
+      throw new Error('Default lookup not found');
+    }
+
+    if (
+      this.defaultQuickCreateFormId &&
+      !this.quickCreateForms.find((f) => f.id === this.defaultQuickCreateFormId)
+    ) {
+      throw new Error('Default quick create form not found');
+    }
+
+    return {
+      logicalName: this.logicalName,
+      defaultFormId: this.defaultFormId,
+      defaultViewId: this.defaultViewId,
+      views: this.views,
+      forms: this.forms,
+      defaultLookupId: this.defaultLookupId,
+      lookups: this.lookups,
+      defaultQuickCreateFormId: this.defaultQuickCreateFormId,
+      quickCreateForms: this.quickCreateForms,
+    };
+  }
+
+  // public createView(view: Omit<View<S>, 'logicalName'>): View<S> {
+  //   return {
+  //     logicalName: this.logicalName,
+  //     ...view,
+  //   };
+  // }
+
+  public defineFormExperience(
+    formExperience: FormExperience<S>
+  ): FormExperience<S> {
+    return formExperience;
+  }
+
+  // public defineForm(form: BaseForm<S>): Form<S> {
+  //   return {
+  //     logicalName: this.logicalName,
+  //     ...form,
+  //   };
+  // }
+
+  // public registerView(view: Omit<View<S>, 'logicalName'>): this {
+  //   this.views.push(this.createView(view));
+  //   return this;
+  // }
+
+  // public registerForm(form: BaseForm<S>): this {
+  //   console.log('registerForm', form);
+  //   if (this.forms.find((f) => f.id === form.id)) {
+  //     throw new Error(
+  //       `Form with id '${form.id}' already exists for entity '${this.logicalName}'`
+  //     );
+  //   }
+
+  //   this.forms.push({
+  //     logicalName: this.logicalName,
+  //     ...form,
+  //   });
+  //   return this;
+  // }
+
+  // public registerLookup(lookup: Omit<ViewLookup<S>, 'logicalName'>): this {
+  //   this.lookups.push({
+  //     logicalName: this.logicalName,
+  //     ...lookup,
+  //   });
+  //   return this;
+  // }
+
+  // public setDefaultViewId(defaultViewId: string): this {
+  //   this.defaultViewId = defaultViewId;
+  //   return this;
+  // }
+
+  // public setDefaultFormId(defaultFormId: string): this {
+  //   this.defaultFormId = defaultFormId;
+  //   return this;
+  // }
+
+  // public setDefaultLookupId(defaultLookupId: string): this {
+  //   this.defaultLookupId = defaultLookupId;
+  //   return this;
+  // }
+
+  // public setDefaultQuickCreateFormId(defaultQuickCreateFormId: string): this {
+  //   this.defaultQuickCreateFormId = defaultQuickCreateFormId;
+  //   return this;
+  // }
+}
+
+export interface SchemaExperienceBuilderDefaults {
+  formCommands?: EntityMainFormCommandItemExperience[][];
+  viewCommands?: EntityMainGridCommandItemExperience[][];
+  subgridCommands?: SubGridCommandItemExperience[][];
+  localizedViewNames?: Record<string, string>; // `All {label}` // key is locale
+}
+
+interface SchemaExperienceBuilderOptions {
+  // localization: {
+  //   defaultViewName: Record<string, (pluralName: string) => string>; // key is locale
+  // };
+}
+
+export class SchemaExperienceBuilder<
+  S extends SchemaAttributes = SchemaAttributes
+> extends BaseSchemaExperienceBuilder<S> {
+  constructor(
+    private schema: Schema<S>,
+    private defaults?: SchemaExperienceBuilderDefaults,
+    private options?: SchemaExperienceBuilderOptions
+  ) {
+    super(schema.logicalName);
+  }
+
+  public defineViewExperience(
+    viewExperience: Pick<ViewExperience<S>, 'filter' | 'defaultSorting'> & {
+      card?: ViewExperience<S>['card'];
+      grid?: ViewExperience<S>['grid'];
+    }
+  ): ViewExperience<S> {
+    const cardView = viewExperience.card ?? this.defineDefaultViewCard();
+    const gridView = viewExperience.grid ?? this.defineDefaultViewGrid();
+
+    return {
+      ...viewExperience,
+      grid: gridView,
+      card: cardView,
+    };
+  }
+
+  public defineDefaultViewGrid(): ViewExperience<S>['grid'] {
+    const columns = [] as ViewExperience<S>['grid']['columns'];
+
+    columns.push({
+      name: this.schema.primaryAttribute,
+    });
+
+    if (this.schema.createdAtAttribute) {
+      columns.push({
+        name: this.schema.createdAtAttribute,
+      });
+    }
+
+    if (this.schema.updatedAtAttribute) {
+      columns.push({
+        name: this.schema.updatedAtAttribute,
+      });
+    }
+
+    return {
+      columns,
+    };
+  }
+
+  public defineDefaultViewCard(): ViewExperience<S>['card'] {
+    return {
+      primaryColumn: this.schema.primaryAttribute,
+    };
+  }
+
+  public defineDefaultViewExperience(): ViewExperience<S> {
+    let defaultSorting: ViewExperience<S>['defaultSorting'] = undefined;
+
+    if (this.schema.updatedAtAttribute) {
+      defaultSorting = [
+        {
+          field: this.schema.updatedAtAttribute,
+          order: 'desc',
+        },
+      ];
+    } else if (this.schema.createdAtAttribute) {
+      defaultSorting = [
+        {
+          field: this.schema.createdAtAttribute,
+          order: 'desc',
+        },
+      ];
+    }
+
+    return {
+      defaultSorting: defaultSorting,
+      grid: this.defineDefaultViewGrid(),
+      card: this.defineDefaultViewCard(),
+    };
+  }
+
+  public defineDefaultFormExperience(): FormExperience<S> {
+    return {
+      headerControls: [],
+      tabs: [
+        {
+          name: 'general',
+          label: 'General',
+          columnCount: 1,
+          tabColumns: [
+            {
+              sections: [
+                {
+                  name: 'general',
+                  label: 'General',
+                  controls: [
+                    {
+                      type: 'standard',
+                      attributeName: this.schema.primaryAttribute,
+                    },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+  }
+
+  private getLocalizedViewNames(): Localized<string> {
+    const langugesSet = new Set<string>();
+
+    this.schema.localizedPluralLabels &&
+      Object.keys(this.schema.localizedPluralLabels).forEach((key) =>
+        langugesSet.add(key)
+      );
+
+    this.defaults?.localizedViewNames &&
+      Object.keys(this.defaults.localizedViewNames).forEach((key) =>
+        langugesSet.add(key)
+      );
+
+    const localizedLabels = Array.from(langugesSet).reduce((acc, key) => {
+      const localizedPluralName =
+        this.schema.localizedPluralLabels?.[key]?.toLowerCase() ??
+        this.schema.pluralLabel.toLowerCase();
+      const localizedPlaceholder =
+        this.defaults?.localizedViewNames?.[key] ?? `All {label}`;
+
+      const localeName = localizedPlaceholder.replace(
+        '{label}',
+        localizedPluralName
+      );
+
+      acc[key] = localeName;
+      return acc;
+    }, {} as Record<string, string>);
+
+    return localizedLabels;
+  }
+
+  private resolveDefaultId<T extends { id: string }>(
+    data: T[],
+    defaultId: string | undefined | null
+  ): string {
+    if (data.length === 0) {
+      throw new Error('No items found');
+    }
+
+    if (!defaultId) {
+      return data[0].id;
+    }
+
+    if (!data.find((x) => x.id === defaultId)) {
+      return data[0].id;
+    }
+
+    return defaultId;
+  }
+
+  public defineExperience(
+    experience: Omit<
+      SchemaExperience<S>,
+      | 'logicalName'
+      | 'forms'
+      | 'views'
+      | 'lookups'
+      | 'defaultViewId'
+      | 'defaultFormId'
+      | 'defaultLookupId'
+      | 'defaultAssociatedViewId'
+      | 'quickCreateForms'
+      | 'viewCommands'
+      | 'subgridCommands'
+      | 'formCommands'
+      | 'associatedViews'
+    > & {
+      forms?: Omit<AsyncForm<S>, 'logicalName'>[];
+      views?: Omit<AsyncView<S>, 'logicalName'>[];
+      lookups?: Omit<AsyncView<S>, 'logicalName'>[];
+      associatedViews?: Omit<AsyncView<S>, 'logicalName'>[];
+      quickCreateForms?: Omit<AsyncQuickCreateForm<S>, 'logicalName'>[];
+      defaultViewId?: string;
+      defaultFormId?: string;
+      defaultLookupId?: string;
+      defaultAssociatedViewId?: string;
+      viewCommands?: SchemaExperience<S>['viewCommands'];
+      subgridCommands?: SchemaExperience<S>['subgridCommands'];
+      formCommands?: SchemaExperience<S>['formCommands'];
+    }
+  ): SchemaExperience<S> {
+    // if (!experience.defaultFormId) {
+    //   throw new Error('Default form is required');
+    // }
+
+    // console.log('experience', experience);
+
+    let lookups = experience.lookups;
+    let views = experience.views;
+    let forms = experience.forms;
+    let associatedViews = experience.associatedViews;
+
+    if (!lookups?.length) {
+      lookups = [
+        {
+          id: 'default',
+          name: 'Default',
+          experience: this.defineViewExperience({}),
+        },
+      ];
+    }
+
+    if (!views?.length) {
+      views = [
+        {
+          id: 'default',
+          name: `All ${this.schema.pluralLabel.toLowerCase()}`,
+          experience: this.defineDefaultViewExperience(),
+          localizedNames: this.getLocalizedViewNames(),
+        },
+      ];
+    }
+
+    if (!associatedViews?.length) {
+      associatedViews = [
+        {
+          id: 'default',
+          name: `All ${this.schema.pluralLabel.toLowerCase()}`,
+          experience: this.defineDefaultViewExperience(),
+          localizedNames: this.getLocalizedViewNames(),
+        },
+      ];
+    }
+
+    if (!forms?.length) {
+      forms = [
+        {
+          id: 'default',
+          name: 'Default',
+          experience: this.defineDefaultFormExperience(),
+        },
+      ];
+    }
+
+    const defaultViewId = this.resolveDefaultId(
+      views,
+      experience.defaultViewId
+    );
+    const defaultFormId = this.resolveDefaultId(
+      forms,
+      experience.defaultFormId
+    );
+    const defaultLookupId = this.resolveDefaultId(
+      lookups,
+      experience.defaultLookupId
+    );
+    const defaultAssociatedViewId = this.resolveDefaultId(
+      associatedViews,
+      experience.defaultAssociatedViewId
+    );
+
+    let defaultQuickCreateFormId = null;
+
+    if (experience.quickCreateForms?.length) {
+      defaultQuickCreateFormId = this.resolveDefaultId(
+        experience.quickCreateForms ?? [],
+        experience.defaultQuickCreateFormId
+      );
+    }
+
+    return {
+      logicalName: this.logicalName,
+      icon: experience.icon,
+      defaultQuickCreateFormId: defaultQuickCreateFormId,
+      defaultFormId,
+      defaultViewId,
+      defaultLookupId,
+      defaultAssociatedViewId,
+      quickCreateForms:
+        experience.quickCreateForms?.map((x) => ({
+          ...x,
+          logicalName: this.logicalName,
+        })) ?? [],
+      views:
+        views.map((x) => ({
+          ...x,
+          logicalName: this.logicalName,
+        })) ?? [],
+      forms:
+        forms.map((x) => ({
+          ...x,
+          logicalName: this.logicalName,
+        })) ?? [],
+      lookups:
+        lookups.map((x) => ({
+          ...x,
+          logicalName: this.logicalName,
+        })) ?? [],
+      associatedViews:
+        associatedViews.map((x) => ({
+          ...x,
+          logicalName: this.logicalName,
+        })) ?? [],
+      formCommands:
+        experience.formCommands ?? this.defaults?.formCommands ?? [],
+      subgridCommands:
+        experience.subgridCommands ?? this.defaults?.subgridCommands ?? [],
+      viewCommands:
+        experience.viewCommands ?? this.defaults?.viewCommands ?? [],
+    };
+  }
+}

package/src/builders/index.ts

@@ -0,0 +1,2 @@
+export { SchemaExperienceBuilder } from './SchemaExperienceBuilder';
+export { CommandBuilder } from './CommandBuilder';

package/src/command/hooks/index.ts

@@ -0,0 +1,2 @@
+export * from './useBaseCommandHandlerContext';
+export * from './useCommands';

package/src/command/hooks/useBaseCommandHandlerContext.ts

@@ -0,0 +1,51 @@
+import { CommandContextBase } from '@headless-adminapp/core/experience/command';
+import { useQueryClient } from '@tanstack/react-query';
+
+import {
+  useOpenAlertDialog,
+  useOpenConfirmDialog,
+  useOpenErrorDialog,
+  useOpenPromptDialog,
+} from '../../dialog/hooks';
+import { useLocale } from '../../locale';
+import { useMetadata } from '../../metadata/hooks';
+import { useProgressIndicator } from '../../progress-indicator/hooks';
+import { useOpenToastNotification } from '../../toast-notification/hooks/useOpenToastNotification';
+import { useDataService } from '../../transport';
+import { UtilityContextState } from '../types';
+
+export function useUtility(): UtilityContextState {
+  const { hideProgressIndicator, showProgressIndicator } =
+    useProgressIndicator();
+  const openAlertDialog = useOpenAlertDialog();
+  const openConfirmDialog = useOpenConfirmDialog();
+  const openErrorDialog = useOpenErrorDialog();
+  const openPromptDialog = useOpenPromptDialog();
+  const openToastNotification = useOpenToastNotification();
+
+  return {
+    hideProgressIndicator,
+    showProgressIndicator,
+    openAlertDialog,
+    openConfirmDialog,
+    openErrorDialog,
+    openPromptDialog,
+    showNotification: openToastNotification,
+  };
+}
+
+export function useBaseCommandHandlerContext(): CommandContextBase {
+  const dataService = useDataService();
+  const queryClient = useQueryClient();
+  const stores = useMetadata();
+  const utility = useUtility();
+  const [locale] = useLocale();
+
+  return {
+    dataService,
+    queryClient,
+    utility,
+    stores,
+    locale,
+  };
+}

package/src/command/hooks/useCommands.ts

@@ -0,0 +1,26 @@
+import { CommandItemExperience } from '@headless-adminapp/core/experience/command';
+import { useMemo, useRef } from 'react';
+
+import { CommandItemExperienceSelector, CommandItemState } from '../types';
+import { transformCommadnGroups } from '../utils';
+
+/***
+ * @description Transforms the command configuration into a format that can be used by the CommandBar component
+ *              and apply the necessary conditions to the commands (disabled, hidden, etc.)
+ */
+export function useCommands<HandlerContext>(
+  commands: CommandItemExperience<HandlerContext>[][],
+  handlerContext: HandlerContext,
+  selector?: CommandItemExperienceSelector<HandlerContext>
+): CommandItemState[][] {
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+
+  return useMemo(() => {
+    return transformCommadnGroups(
+      commands,
+      handlerContext,
+      selectorRef.current
+    );
+  }, [commands, handlerContext]);
+}

package/src/command/index.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './hooks';

package/src/command/types.ts

@@ -0,0 +1,116 @@
+import { CommandItemExperience } from '@headless-adminapp/core/experience/command';
+import {
+  ConfirmDialogOptions,
+  PromptDialogOptions,
+} from '@headless-adminapp/core/experience/dialog';
+import {
+  InferredSchemaType,
+  SchemaAttributes,
+} from '@headless-adminapp/core/schema';
+import {
+  ArrayGroupWithAtLeastOne,
+  Localized,
+} from '@headless-adminapp/core/types';
+import { Icon } from '@headless-adminapp/icons';
+
+interface ConfirmResult {
+  confirmed: boolean;
+}
+export interface UtilityContextState {
+  showProgressIndicator: (message?: string) => void;
+  hideProgressIndicator: () => void;
+  openAlertDialog(options: {
+    text: string;
+    title?: string;
+    confirmButtonLabel?: string;
+  }): Promise<void>;
+  openConfirmDialog(
+    options: Omit<
+      ConfirmDialogOptions,
+      'type' | 'onConfirm' | 'onDismiss' | 'onCancel'
+    >
+  ): Promise<ConfirmResult | null>;
+  openErrorDialog(options: {
+    text: string;
+    title?: string;
+    confirmButtonLabel?: string;
+  }): void;
+  openPromptDialog: <SA extends SchemaAttributes = SchemaAttributes>(
+    options: Omit<
+      PromptDialogOptions<SA>,
+      'type' | 'onConfirm' | 'onClose' | 'onCancel'
+    >
+  ) => Promise<InferredSchemaType<SA> | null>;
+  showNotification: (options: {
+    text: string;
+    title?: string;
+    actions?: { text: string; onClick: () => void }[];
+    type?: 'info' | 'success' | 'warning' | 'error';
+  }) => void;
+}
+
+interface BaseCommandState {
+  Icon: Icon;
+  iconPosition?: 'before' | 'after';
+  danger?: boolean;
+  hidden?: boolean;
+}
+
+interface ActionableCommandState {
+  onClick?: () => void;
+  disabled?: boolean;
+  hidden?: boolean;
+}
+
+export interface IconButtonCommandState
+  extends BaseCommandState,
+    ActionableCommandState {
+  type: 'icon';
+  isQuickAction?: boolean;
+}
+
+export interface ButtonCommandState
+  extends BaseCommandState,
+    ActionableCommandState {
+  type: 'button';
+  text: string;
+  isQuickAction?: boolean;
+  isContextMenu?: boolean; // Keep visible for right click context menu
+  localizedTexts?: Localized<string>;
+}
+
+export interface LabelCommandState extends BaseCommandState {
+  type: 'label';
+  text: string;
+  localizedTexts?: Localized<string>;
+}
+
+export interface MenuItemCommandState
+  extends BaseCommandState,
+    ActionableCommandState {
+  text: string;
+  localizedTexts?: Localized<string>;
+  items?: ArrayGroupWithAtLeastOne<MenuItemCommandState>;
+}
+
+export interface MenuComandState
+  extends BaseCommandState,
+    ActionableCommandState {
+  type: 'menu';
+  text: string;
+  localizedTexts?: Localized<string>;
+  isContextMenu?: boolean; // Keep visible for right click context menu
+  items: ArrayGroupWithAtLeastOne<MenuItemCommandState>;
+}
+
+export type CommandItemState =
+  | IconButtonCommandState
+  | ButtonCommandState
+  | MenuComandState
+  | LabelCommandState;
+
+export type Selector<T> = (value: T) => boolean;
+
+export type CommandItemExperienceSelector<Context> = Selector<
+  CommandItemExperience<Context>
+>;