@axinom/mosaic-agent-skills 0.0.1

package/skills/generate-explorer-station/refs/templates/bulk-edit.md

@@ -0,0 +1,369 @@
+---
+name: explorer-bulk-edit
+input:
+  - EntityFeatures
+  - DiscoveredPaths
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{EntityPlural}Explorer/BulkEdit/{EntityPlural}BulkEditConfig.ts'
+    description: 'Bulk edit configuration with field mappings'
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{EntityPlural}Explorer/BulkEdit/{EntityPlural}BulkEdit.tsx'
+    description: 'Bulk edit component'
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{EntityPlural}Explorer/BulkEdit/index.ts'
+    description: 'Barrel export for bulk edit'
+---
+
+# Generate BulkEdit Files
+
+**Generate only if:** `features.mutations.bulkEdit === true`
+
+---
+
+## 1. {EntityPlural}BulkEditConfig.ts
+
+**Discovery:** labelMapper, typeMapper utilities
+
+- Pattern: `labelMapper|typeMapper`
+- Locations: `Util/BulkEdit/`, `utils/`
+
+```typescript
+import { BulkEdit{EntityPlural}AsyncFormFieldsConfig } from '../../../../generated/graphql';
+import { labelMapper, typeMapper } from '{discoveredPath}/BulkEdit';
+
+export const {EntityPlural}BulkEditConfig = (() => {
+  const fields: Partial<typeof BulkEdit{EntityPlural}AsyncFormFieldsConfig.fields> = {
+    ...BulkEdit{EntityPlural}AsyncFormFieldsConfig.fields,
+  };
+
+  labelMapper(fields, {
+    // Map field names to human-readable labels
+    {entityCamel}{AssociationPlural}Add: '{AssociationLabel} (Add)',
+    {entityCamel}{AssociationPlural}Remove: '{AssociationLabel} (Remove)',
+  });
+
+  typeMapper(fields, {
+    // Map fields to custom component types (if needed)
+    // Example: {associationField}Add: 'CustomSelection',
+  });
+
+  // Delete unwanted fields
+  delete fields['unwantedField'];
+
+  return {
+    ...BulkEdit{EntityPlural}AsyncFormFieldsConfig,
+    fields,
+  };
+})();
+```
+
+---
+
+## 2. {EntityPlural}BulkEdit.tsx
+
+**Discovery:** BulkEdit utilities
+
+- Pattern: `getBulkEditImageSelectField|getVideoSelectField`
+- Locations: `Util/BulkEdit/`, `utils/`
+
+```typescript
+import { BulkEditFormFieldsConfigConverter, defaultComponentMap } from '@axinom/mosaic-ui';
+import React from 'react';
+// If features.capabilities.images !== undefined || features.capabilities.videos !== undefined:
+import { {Entity}ImageType } from '../../../../generated/graphql';
+import { getBulkEditImageSelectField, getVideoSelectField } from '{discoveredPath}/BulkEdit';
+// End if
+import { {EntityPlural}BulkEditConfig } from './{EntityPlural}BulkEditConfig';
+
+export const {EntityPlural}BulkEdit: React.FC = () => {
+  const componentMap = {
+    ...defaultComponentMap,
+    // If features.capabilities.images?.imageTypeValues.includes('COVER'):
+    CoverImageSelection: getBulkEditImageSelectField({Entity}ImageType.Cover, '{entityCamel}', 1),
+    // If features.capabilities.videos?.trailersConnection !== undefined:
+    VideoSelection: getVideoSelectField('TRAILER'),
+    // Custom field components as needed
+  };
+
+  const fields = {EntityPlural}BulkEditConfig.fields;
+
+  return BulkEditFormFieldsConfigConverter(
+    Object.entries(fields)
+      .sort(([, a], [, b]) => (a.label || '').localeCompare(b.label || ''))
+      .reduce((acc, [key, value]) => {
+        acc[key] = value;
+        return acc;
+      }, {}),
+    componentMap,
+  );
+};
+```
+
+---
+
+## 3. index.ts
+
+```typescript
+export * from './{EntityPlural}BulkEdit';
+export * from './{EntityPlural}BulkEditConfig';
+```
+
+---
+
+## Fallback
+
+If BulkEdit utilities (`labelMapper`, `typeMapper`,
+`getBulkEditImageSelectField`, `getVideoSelectField`, `MainVideoSelectionField`)
+are not found in the project, create them in the `~/workflows/src/Util/BulkEdit`
+folder and reuse.
+
+If the `{discoveredPaths.extensionsContextPath}` is empty, it means the project
+does not support rendering external components (i.e. image/video rendering), and
+we can skip such component usage in BulkEdit and add a `TODO` for later. Other
+BulkEdit fields will work without custom image/videos components.
+
+### Create BulkEdit/helpers.ts
+
+```typescript
+import { BulkEditFieldConfigMap } from '@axinom/mosaic-ui';
+
+export const labelMapper = <T extends BulkEditFieldConfigMap>(
+  fields: Partial<T>,
+  labelMap: {
+    [key in keyof T]?: string;
+  },
+): void => {
+  for (const key in fields) {
+    const labelValue = labelMap[key];
+    const fieldValue = fields[key];
+    if (labelValue && fieldValue) {
+      fieldValue.label = labelValue;
+    }
+  }
+};
+
+export const typeMapper = <T extends BulkEditFieldConfigMap>(
+  fields: Partial<T>,
+  typeMap: {
+    [key in keyof T]?: string;
+  },
+): void => {
+  for (const key in fields) {
+    const typeValue = typeMap[key];
+    const fieldValue = fields[key];
+    if (typeValue && fieldValue) {
+      fieldValue.type = typeValue;
+    }
+  }
+};
+```
+
+### Create BulkEdit/ImageSelectField.tsx (if images capability exists)
+
+```tsx
+import { ImageSelectFieldProps } from '@axinom/mosaic-managed-workflow-integration';
+import { BulkEditEnumType } from '@axinom/mosaic-ui';
+import React, { useContext } from 'react';
+import { ExtensionsContext } from '{discoveredPaths.extensionsContextPath}';
+
+export const getBulkEditImageSelectField: (
+  type: string,
+  scope: string,
+  maxItems?: number,
+) => React.FC<ImageSelectFieldProps> = (type, scope, maxItems) => {
+  const Component: React.FC<ImageSelectFieldProps> = (props) => {
+    const { ImageSelectField } = useContext(ExtensionsContext);
+    return (
+      <ImageSelectField
+        {...props}
+        value={props.value ? props.value.map((item) => item.imageId) : []}
+        onChange={(event) => {
+          const value = (
+            event as { currentTarget: { value: string[] } }
+          ).currentTarget.value.map((id) => ({
+            imageId: id,
+            imageType: new BulkEditEnumType(type),
+          }));
+
+          props.onChange({
+            currentTarget: {
+              name: props.name,
+              value,
+            },
+          });
+        }}
+        imageType={`${scope}_${type.toLowerCase()}`}
+        maxItems={maxItems}
+      />
+    );
+  };
+  Component.displayName = `ImageSelectField_${type}`;
+  return Component;
+};
+```
+
+### Create BulkEdit/VideoSelectField.tsx (if videos capability exists)
+
+```tsx
+import { VideoSelectFieldProps } from '@axinom/mosaic-video-workflow-integration';
+import React, { useContext } from 'react';
+import { ExtensionsContext } from '{discoveredPaths.extensionsContextPath}';
+
+export const getVideoSelectField: (
+  type: string,
+  maxItems?: number,
+) => React.FC<VideoSelectFieldProps> = (type, maxItems) => {
+  const Component: React.FC<VideoSelectFieldProps> = (props) => {
+    const { VideoSelectField } = useContext(ExtensionsContext);
+    const { value, onChange, name } = props;
+
+    return (
+      <VideoSelectField
+        {...props}
+        defaultFilterTag={type}
+        value={value?.map((trailer) => trailer.videoId) ?? []}
+        onChange={(event) => {
+          const value = (
+            event as { currentTarget: { value: string[] } }
+          ).currentTarget.value.map((id) => ({ videoId: id }));
+          onChange &&
+            onChange({
+              ...(event as React.ChangeEvent<HTMLInputElement>),
+              currentTarget: {
+                ...(event as React.ChangeEvent<HTMLInputElement>).currentTarget,
+                name: name,
+                value: value,
+              },
+            });
+        }}
+        maxItems={maxItems}
+      />
+    );
+  };
+  Component.displayName = `VideoSelectField_${type}`;
+  return Component;
+};
+```
+
+### Create BulkEdit/MainVideoSelectField.tsx (if mainVideoField exists)
+
+```tsx
+import { SingleLineTextProps } from '@axinom/mosaic-ui';
+import React, { useContext } from 'react';
+import { ExtensionsContext } from '{discoveredPaths.extensionsContextPath}';
+
+export const MainVideoSelectionField: React.FC<SingleLineTextProps> = (
+  props,
+) => {
+  const { VideoSelectField } = useContext(ExtensionsContext);
+  const { value, onChange, name, label = '' } = props;
+
+  return (
+    <VideoSelectField
+      {...props}
+      defaultFilterTag="MAIN"
+      label={label}
+      value={value ? [value] : []}
+      onChange={(event) => {
+        const value = (event as React.ChangeEvent<HTMLInputElement>)
+          .currentTarget.value[0];
+        onChange &&
+          onChange({
+            ...(event as React.ChangeEvent<HTMLInputElement>),
+            currentTarget: {
+              ...(event as React.ChangeEvent<HTMLInputElement>).currentTarget,
+              name: name,
+              value: value,
+            },
+          });
+      }}
+      maxItems={1}
+    />
+  );
+};
+```
+
+### Update {EntityPlural}BulkEdit.tsx to import from local directory
+
+```typescript
+import { BulkEditFormFieldsConfigConverter, defaultComponentMap } from '@axinom/mosaic-ui';
+import React from 'react';
+// Import from local BulkEdit directory
+import { getBulkEditImageSelectField } from './helpers/ImageSelectField';
+import { getVideoSelectField } from './helpers/VideoSelectField';
+import { MainVideoSelectionField } from './helpers/MainVideoSelectField';
+// If features.capabilities.images !== undefined || features.capabilities.videos !== undefined:
+import { {Entity}ImageType } from '../../../../generated/graphql';
+// End if
+import { {EntityPlural}BulkEditConfig } from './{EntityPlural}BulkEditConfig';
+
+export const {EntityPlural}BulkEdit: React.FC = () => {
+  const componentMap = {
+    ...defaultComponentMap,
+    // If features.capabilities.images?.imageTypeValues.includes('COVER'):
+    CoverImageSelection: getBulkEditImageSelectField({Entity}ImageType.Cover, '{entityCamel}', 1),
+    // If features.capabilities.videos?.mainVideoField:
+    MainVideoSelection: MainVideoSelectionField,
+    // If features.capabilities.videos?.trailersConnection !== undefined:
+    VideoSelection: getVideoSelectField('TRAILER'),
+    // Custom field components as needed
+  };
+
+  const fields = {EntityPlural}BulkEditConfig.fields;
+
+  return BulkEditFormFieldsConfigConverter(
+    Object.entries(fields)
+      .sort(([, a], [, b]) => (a.label || '').localeCompare(b.label || ''))
+      .reduce((acc, [key, value]) => {
+        acc[key] = value;
+        return acc;
+      }, {}),
+    componentMap,
+  );
+};
+```
+
+## Example (Product - simple)
+
+```typescript
+// ProductsBulkEditConfig.ts
+import { BulkEditProductsAsyncFormFieldsConfig } from '../../../../generated/graphql';
+import { labelMapper, typeMapper } from '../../../../Util/BulkEdit';
+
+export const ProductsBulkEditConfig = (() => {
+  const fields: Partial<typeof BulkEditProductsAsyncFormFieldsConfig.fields> = {
+    ...BulkEditProductsAsyncFormFieldsConfig.fields,
+  };
+
+  labelMapper(fields, {
+    productsProductCategoriesAdd: 'Categories (Add)',
+    productsProductCategoriesRemove: 'Categories (Remove)',
+  });
+
+  return {
+    ...BulkEditProductsAsyncFormFieldsConfig,
+    fields,
+  };
+})();
+
+// ProductsBulkEdit.tsx
+import {
+  BulkEditFormFieldsConfigConverter,
+  defaultComponentMap,
+} from '@axinom/mosaic-ui';
+import React from 'react';
+import { ProductsBulkEditConfig } from './ProductsBulkEditConfig';
+
+export const ProductsBulkEdit: React.FC = () => {
+  const componentMap = { ...defaultComponentMap };
+  const fields = ProductsBulkEditConfig.fields;
+
+  return BulkEditFormFieldsConfigConverter(
+    Object.entries(fields)
+      .sort(([, a], [, b]) => (a.label || '').localeCompare(b.label || ''))
+      .reduce((acc, [key, value]) => {
+        acc[key] = value;
+        return acc;
+      }, {}),
+    componentMap,
+  );
+};
+```

package/skills/generate-explorer-station/refs/templates/common/bulk-actions.md

@@ -0,0 +1,64 @@
+---
+name: explorer-bulk-actions
+input:
+  - EntityFeatures
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{EntityPlural}Explorer/common/{EntityPlural}.bulkActions.ts'
+    description: 'Bulk action hooks and actions'
+---
+
+# Generate bulkActions.ts
+
+**Generate only if:** `features.mutations.bulkActions === true`
+
+Generate mutation hooks and actions for each mutation in
+`features.mutations.names.bulkActions`.
+
+## Template
+
+```typescript
+import { ExplorerBulkAction, IconName, ItemSelection, PageHeaderActionType } from '@axinom/mosaic-ui';
+import { client } from '{discoveredPath}/apolloClient';
+import {
+  // Import hooks for each bulk action mutation
+  // Use{PascalCaseMutationName}Mutation for each mutation in features.mutations.names.bulkActions
+} from '../../../../generated/graphql';
+import { use{EntityPlural}Filters } from './{EntityPlural}.filters';
+import { {Entity}Data } from './{EntityPlural}.types';
+
+export function use{EntityPlural}BulkActions(): {
+  readonly bulkActions: ExplorerBulkAction<{Entity}Data>[];
+} {
+  const { transformFilters } = use{EntityPlural}Filters();
+
+  // For each mutation in features.mutations.names.bulkActions, create hook and action
+  // Example for "deleteMovies":
+  const [bulkDelete{EntityPlural}] = useBulkDelete{EntityPlural}Mutation({
+    client,
+    fetchPolicy: 'no-cache',
+  });
+
+  const deleteBulkAction: ExplorerBulkAction<{Entity}Data> = {
+    label: 'Delete',
+    onClick: async (arg?: ItemSelection<{Entity}Data>) => {
+      switch (arg?.mode) {
+        case 'SELECT_ALL':
+          await bulkDelete{EntityPlural}({ variables: { filter: transformFilters(arg.filters) } });
+          break;
+        case 'SINGLE_ITEMS':
+          await bulkDelete{EntityPlural}({
+            variables: { filter: { id: { in: arg.items?.map((item) => item.id) } } },
+          });
+          break;
+      }
+    },
+    actionType: PageHeaderActionType.Context,
+    confirmationMode: 'Simple',
+    icon: IconName.Delete,
+    reloadData: true,
+  };
+
+  // Return all bulk actions
+  return { bulkActions: [deleteBulkAction /* , other actions */] };
+}
+```

package/skills/generate-explorer-station/refs/templates/common/columns.md

@@ -0,0 +1,131 @@
+---
+name: explorer-columns
+input:
+  - EntityFeatures
+  - selectedColumns
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{EntityPlural}Explorer/common/{EntityPlural}.columns.ts'
+    description: 'Column definitions with renderers'
+---
+
+# Generate columns.ts
+
+For each selected column from a scalar field, check
+`features.fields.scalars[].semanticHint`. If present, apply appropriate
+renderer:
+
+- `duration` → `renderDuration` (seconds to "2h 30m")
+- `fileSize` → `renderFileSize` (bytes to "1.5 GB")
+- `currency` → `renderCurrency` (with $ and commas)
+- `percentage` → `renderPercentage` (0.45 to "45%")
+
+For enum scalar fields (check `features.fields.scalars[].enumType`), use
+getEnumLabel renderer:
+
+- Discover `getEnumLabel` in project (typically in `Util/StringEnumMapper/`)
+- Wrap in arrow function with type casting:
+  `(value) => getEnumLabel(value as string)`
+
+Discover renderers in project first, fallback to inline implementations (see end
+of this section).
+
+## Template
+
+```typescript
+import { Column, createConnectionRenderer, DateRenderer } from '@axinom/mosaic-ui';
+// If features.capabilities.images !== undefined:
+import { createThumbnailAndStateRenderer } from '@axinom/mosaic-managed-workflow-integration';
+// End if
+// If enum fields in selectedColumns:
+import { getEnumLabel } from '{discoveredPath}/StringEnumMapper/StringEnumMapper';
+// End if
+import { {Entity}Data } from './{EntityPlural}.types';
+
+export const {entityCamel}Columns: Column<{Entity}Data>[] = [
+  // If features.capabilities.images !== undefined:
+  {
+    propertyName: '{entityCamel}Images',
+    label: 'Thumb',
+    render: createThumbnailAndStateRenderer('{entityCamel}Images'),
+    size: '80px',
+  },
+
+  // Title field:
+  { label: '{TitleLabel}', propertyName: '{titleField}', size: '2fr' },
+
+  // For each selected scalar column:
+  // - No semanticHint and no enumType: { label, propertyName }
+  // - Has semanticHint: { label, propertyName, render: renderer }
+  // - Has enumType: { label, propertyName, render: (value) => getEnumLabel(value as string) }
+
+  // Boolean fields:
+  {
+    label: 'Visible',
+    propertyName: 'isVisible',
+    render: (value: unknown) => (value === true ? 'Yes' : 'No'),
+  }
+
+  // Enum fields:
+  { label: 'Status', propertyName: 'status', render: (value) => getEnumLabel(value as string) },
+
+  // TagLike associations:
+  {
+    label: '{Label}',
+    propertyName: '{entityCamel}{AssociationPlural}',
+    sortable: false,
+    render: createConnectionRenderer((node: any) => node.{displayField}),
+  },
+
+  // ManyToMany associations:
+  {
+    label: '{Label}',
+    propertyName: '{entityCamel}{AssociationPlural}',
+    sortable: false,
+    render: createConnectionRenderer((node: any) => node.{relatedCamel}?.{displayField}),
+  },
+
+  // Date fields:
+  { label: 'Updated At', propertyName: 'updatedDate', render: DateRenderer },
+];
+```
+
+## Semantic Renderer Fallbacks
+
+```typescript
+const renderDuration = (value: unknown): string => {
+  const seconds = value as number | null | undefined;
+  if (!seconds) return '';
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = seconds % 60;
+  return [h && `${h}h`, m && `${m}m`, s && `${s}s`].filter(Boolean).join(' ');
+};
+
+const renderFileSize = (value: unknown): string => {
+  const bytes = value as number | null | undefined;
+  if (!bytes) return '';
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let size = bytes;
+  let i = 0;
+  while (size >= 1024 && i < 4) {
+    size /= 1024;
+    i++;
+  }
+  return `${size.toFixed(i ? 2 : 0)} ${units[i]}`;
+};
+
+const renderCurrency = (value: unknown): string => {
+  const num = value as number | null | undefined;
+  if (num == null) return '';
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+  }).format(num);
+};
+
+const renderPercentage = (value: unknown): string => {
+  const num = value as number | null | undefined;
+  if (num == null) return '';
+  return `${(num * 100).toFixed(1)}%`;
+};
+```

package/skills/generate-explorer-station/refs/templates/common/data-provider.md

@@ -0,0 +1,83 @@
+---
+name: explorer-data-provider
+input:
+  - EntityFeatures
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{EntityPlural}Explorer/common/{EntityPlural}.dataProvider.ts'
+    description: 'Data provider for loading and subscribing to data'
+---
+
+# Generate dataProvider.ts
+
+**Discovery:** Apollo client
+
+- Pattern: `export.*client.*ApolloClient`
+- Locations: `src/`, `apolloClient.ts`, `client.ts`
+
+## Template
+
+```typescript
+import { ExplorerDataProvider, FilterValues, sortToPostGraphileOrderBy } from '@axinom/mosaic-ui';
+import { client } from '{discoveredPath}/apolloClient';
+import {
+  {Entity}Filter,
+  {EntityPlural}Document,
+  {EntityPlural}OrderBy,
+  {EntityPlural}Query,
+  {EntityPlural}QueryVariables,
+  // If features.queries.subscription === true:
+  {EntityPlural}MutatedDocument,
+  {EntityPlural}MutatedSubscription,
+  {Entity}SubscriptionEventKey,
+} from '../../../../generated/graphql';
+import { {Entity}Data } from './{EntityPlural}.types';
+
+export const create{EntityPlural}DataProvider = (
+  transformFilters: (filters: FilterValues<{Entity}Data>) => {Entity}Filter | undefined,
+): ExplorerDataProvider<{Entity}Data> => ({
+  loadData: async ({ pagingInformation, sorting, filters }) => {
+    const result = await client.query<{EntityPlural}Query, {EntityPlural}QueryVariables>({
+      query: {EntityPlural}Document,
+      variables: {
+        filter: transformFilters(filters),
+        orderBy: sortToPostGraphileOrderBy(sorting, {EntityPlural}OrderBy),
+        after: pagingInformation,
+      },
+      fetchPolicy: 'network-only',
+    });
+
+    return {
+      data: result.data.filtered?.nodes ?? [],
+      totalCount: result.data.nonFiltered?.totalCount as number,
+      filteredCount: result.data.filtered?.totalCount as number,
+      hasMoreData: result.data.filtered?.pageInfo.hasNextPage || false,
+      pagingInformation: result.data.filtered?.pageInfo.endCursor,
+    };
+  },
+
+  // If features.queries.subscription === true:
+  connect: ({ change, add, remove }) => {
+    const subscription = client
+      .subscribe<{EntityPlural}MutatedSubscription>({ query: {EntityPlural}MutatedDocument })
+      .subscribe((e) => {
+        switch (e.data?.{entityCamel}Mutated?.eventKey) {
+          case {Entity}SubscriptionEventKey.{Entity}Changed:
+            if (e.data.{entityCamel}Mutated.{entityCamel}) {
+              change(e.data.{entityCamel}Mutated.id, e.data.{entityCamel}Mutated.{entityCamel});
+            }
+            break;
+          case {Entity}SubscriptionEventKey.{Entity}Deleted:
+            remove(e.data.{entityCamel}Mutated.id);
+            break;
+          case {Entity}SubscriptionEventKey.{Entity}Created:
+            if (e.data.{entityCamel}Mutated.{entityCamel}) {
+              add(e.data.{entityCamel}Mutated.{entityCamel});
+            }
+            break;
+        }
+      });
+
+    return () => { subscription.unsubscribe(); };
+  },
+});
+```