@axinom/mosaic-agent-skills 0.0.1

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

@@ -0,0 +1,220 @@
+---
+name: explorer-filters
+input:
+  - EntityFeatures
+  - selectedFilters
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{EntityPlural}Explorer/common/{EntityPlural}.filters.ts'
+    description: 'Filter options and transform functions'
+---
+
+# Generate filters.ts
+
+**Discovery:** FilterUtils
+
+- Pattern: `createTextFilter|createOptionsFilter|createSearchableFilter`
+- Locations: `Util/FilterUtils/`, `utils/`
+
+**Discovery:** getEnumLabel (if enum filters exist)
+
+- Pattern: `getEnumLabel`
+- Locations: `Util/StringEnumMapper/`, `utils/`
+
+## Template
+
+```typescript
+import { createDateRangeFilterValidators, filterToPostGraphileFilter, FilterType, FilterValues, transformRange } from '@axinom/mosaic-ui';
+import { client } from '{discoveredPath}/apolloClient';
+import { {Entity}Filter, /* filter option query types */ } from '../../../../generated/graphql';
+import { createTextFilter, createSearchableFilter, createOptionsFilter, createDateRangeFilters, createNumericFilter } from '{discoveredPath}/FilterUtils';
+// If enum filters:
+import { getEnumLabel } from '{discoveredPath}/StringEnumMapper/StringEnumMapper';
+import { {Entity}Data } from './{EntityPlural}.types';
+
+// If associations in filters:
+function use{Entity}FilterData(): {
+  {associationCamelPlural}: /* type */;
+} {
+  const {associationCamelPlural} = use{Entity}{association.label}FilterOptionsQuery({
+    client,
+    variables: { orderBy: [{association.orderByType}.{DisplayField}Asc] },
+    fetchPolicy: 'network-only',
+  });
+
+  return {
+    {associationCamelPlural}: {associationCamelPlural}.data?.{associationCamelPlural}?.nodes ?? [],
+  };
+}
+
+export function use{EntityPlural}Filters(): {
+  readonly filterOptions: FilterType<{Entity}Data>[];
+  readonly transformFilters: (filters: FilterValues<{Entity}Data>) => {Entity}Filter | undefined;
+} {
+  const [createFromDateFilterValidator, createToDateFilterValidator] =
+    createDateRangeFilterValidators<{Entity}Data>();
+
+  // If associations:
+  const { {associationCamelPlural} } = use{Entity}FilterData();
+
+  const filterOptions: FilterType<{Entity}Data>[] = [
+    createTextFilter('Title', '{titleField}'),
+    // Searchable association:
+    createSearchableFilter(
+      '{AssociationLabel}',
+      '{entityCamel}{AssociationPlural}',
+      {associationCamelPlural},
+      (item) => item?.{displayField} ?? '',
+      'Search {AssociationLabel}',
+    ),
+    // Date range:
+    ...createDateRangeFilters(
+      '{dateField}',
+      '{Label} (From)',
+      '{Label} (To)',
+      createFromDateFilterValidator,
+      createToDateFilterValidator,
+    ),
+    createNumericFilter('ID', 'id'),
+  ];
+
+  const transformFilters = (filters: FilterValues<{Entity}Data>): {Entity}Filter | undefined => {
+    return filterToPostGraphileFilter<{Entity}Filter>(filters, {
+      {titleField}: 'includesInsensitive',
+      {entityCamel}{AssociationPlural}: ['some', '{displayField}', 'includesInsensitive'],
+      {dateField}: transformRange,
+      id: 'equalTo',
+    });
+  };
+
+  return { filterOptions, transformFilters };
+}
+```
+
+## Fallbacks
+
+If utilities not found, use inline implementations:
+
+```typescript
+// If FilterUtils not found:
+// TODO: [MISSING_UTILITY] FilterUtils not found - using inline implementations
+import {
+  Data,
+  FilterType,
+  FilterTypes,
+  FilterValidatorFunction,
+} from '@axinom/mosaic-ui';
+
+function createTextFilter<T extends Data>(
+  label: string,
+  property: keyof T,
+): FilterType<T> {
+  return { label, property, type: FilterTypes.FreeText };
+}
+
+function createNumericFilter<T extends Data>(
+  label: string,
+  property: keyof T,
+): FilterType<T> {
+  return { label, property, type: FilterTypes.Numeric };
+}
+
+function createOptionsFilter<T extends Data>(
+  label: string,
+  property: keyof T,
+  options: { label: string; value: string | number | boolean }[],
+): FilterType<T> {
+  return { label, property, type: FilterTypes.Options, options };
+}
+
+function createSearchableFilter<T extends Data, K>(
+  label: string,
+  property: keyof T,
+  items: K[] | undefined,
+  labelSelector: (item: K) => string,
+  placeholder: string,
+  maxItems = 10,
+): FilterType<T> {
+  return {
+    label,
+    property,
+    type: FilterTypes.SearcheableOptions,
+    optionsProvider: createSearchableOptionsProvider(
+      items,
+      labelSelector,
+      labelSelector,
+      maxItems,
+    ),
+    searchInputPlaceholder: placeholder,
+    maxItems,
+  };
+}
+
+function createDateRangeFilters<T extends Data>(
+  property: keyof T,
+  fromLabel: string,
+  toLabel: string,
+  createFromValidator: (key: keyof T) => FilterValidatorFunction<T>,
+  createToValidator: (key: keyof T) => FilterValidatorFunction<T>,
+): FilterType<T>[] {
+  return [
+    {
+      label: fromLabel,
+      property,
+      type: FilterTypes.Date,
+      onValidate: createFromValidator(property),
+    },
+    {
+      label: toLabel,
+      property,
+      type: FilterTypes.Date,
+      onValidate: createToValidator(property),
+    },
+  ];
+}
+
+function createSearchableOptionsProvider<T>(
+  items: T[] | undefined,
+  labelSelector: (item: T) => string,
+  valueSelector: (item: T) => string = labelSelector,
+  maxItems = 10,
+): (searchText: string) => { label: string; value: string }[] {
+  return (searchText: string) => {
+    const searchLower = searchText.trim().toLowerCase();
+    const uniqueItems = removeDuplicatesBy(items || [], valueSelector);
+
+    return (
+      uniqueItems
+        .filter((item) =>
+          labelSelector(item).toLowerCase().includes(searchLower),
+        )
+        .slice(0, maxItems)
+        .map((item) => ({
+          label: labelSelector(item),
+          value: valueSelector(item),
+        })) || []
+    );
+  };
+}
+
+function removeDuplicatesBy<T, K extends string | number>(
+  array: T[],
+  keySelector: (item: T) => K | null | undefined,
+): T[] {
+  const seen = new Set<K>();
+  return array.filter((item) => {
+    const key = keySelector(item);
+    if (key != null && !seen.has(key)) {
+      seen.add(key);
+      return true;
+    }
+    return false;
+  });
+}
+
+function getEnumLabel(value: string): string {
+  return value
+    .split('_')
+    .map((w) => w.charAt(0) + w.slice(1).toLowerCase())
+    .join(' ');
+}
+```

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

@@ -0,0 +1,45 @@
+---
+name: explorer-inline-actions
+input:
+  - EntityFeatures
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{EntityPlural}Explorer/common/{EntityPlural}.inlineActions.ts'
+    description: 'Inline action menu generator'
+---
+
+# Generate inlineActions.ts
+
+**Always generate** with TODOs for missing features.
+
+## Template
+
+```typescript
+import { ActionData, IconName } from '@axinom/mosaic-ui';
+import { {Entity}Data } from './{EntityPlural}.types';
+
+export function use{EntityPlural}InlineActions(): {
+  readonly generateInlineMenuActions: (data: {Entity}Data) => ActionData[];
+} {
+  const generateInlineMenuActions = ({ id }: {Entity}Data): ActionData[] => {
+    return [
+      // TODO: Add Delete inline action once the Details station with mutations exists
+      // Example structure:
+      // {
+      //   label: 'Delete',
+      //   onActionSelected: async () => {
+      //     await deleteEntityMutation({ variables: { input: { id } } });
+      //   },
+      //   icon: IconName.Delete,
+      //   confirmationMode: 'Simple',
+      // },
+      // TODO: Add Open Details inline action once Details station exists
+      // {
+      //   label: 'Open Details',
+      //   path: `/{kebabCasePlural}/${id}`,
+      // },
+    ];
+  };
+
+  return { generateInlineMenuActions };
+}
+```

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

@@ -0,0 +1,28 @@
+---
+name: explorer-types
+input:
+  - EntityFeatures
+  - Generated GraphQL types
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{EntityPlural}Explorer/common/{EntityPlural}.types.ts'
+    description: 'TypeScript type definitions'
+---
+
+# Generate types.ts
+
+## Template
+
+```typescript
+import { SelectionExplorerProps } from '@axinom/mosaic-ui';
+import { {EntityPlural}Query } from '../../../../generated/graphql';
+
+export type {Entity}Data = NonNullable<{EntityPlural}Query['filtered']>['nodes'][number];
+
+interface Props {
+  excludeItems?: {Entity}Data['id'][];
+}
+
+export interface {Entity}SelectionExplorerProps
+  extends Omit<SelectionExplorerProps<{Entity}Data>, 'columns' | 'dataProvider' | 'filterOptions'>,
+    Props {}
+```

package/skills/generate-explorer-station/refs/templates/graphql-operations.md

@@ -0,0 +1,235 @@
+---
+name: explorer-graphql-operations
+input:
+  - EntityFeatures
+  - selectedColumns
+  - selectedFilters
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{EntityPlural}Explorer/{EntityPlural}.graphql'
+    description: 'GraphQL fragment, query, and filter queries'
+---
+
+# Generate GraphQL File
+
+Single file with all operations using exact names from EntityFeatures.
+
+## Template
+
+```graphql
+# Fragment - all fields based on the `EntityFeatures` needed for `selectedColumns` & `selectedFilters`
+fragment {features.name}ExplorerProperties on {features.schema.entity} {
+  id
+  {features.titleField}
+
+  # Scalar fields from `selectedColumns` and `selectedFilters`
+  {scalarField1}
+  {scalarField2}
+
+  # Image capability (if features.capabilities.images)
+  {features.capabilities.images.connectionField}(condition: { imageType: COVER }) {
+    nodes {
+      imageId
+    }
+  }
+
+  # TagLike associations from selectedColumns/selectedFilters
+  # Use: association.connectionField, association.displayField
+  {association.connectionField} {
+    nodes {
+      {association.displayField}
+    }
+  }
+
+  # ManyToMany associations from selectedColumns/selectedFilters
+  # Use: association.connectionField, association.relatedField, association.displayField
+  {association.connectionField} {
+    nodes {
+      {association.relatedField} {
+        {association.displayField}
+      }
+    }
+  }
+
+  # Audit fields
+  createdDate
+  updatedDate
+}
+
+# Main query (always)
+query {features.namePlural}(
+  $filter: {features.schema.filter},
+  $orderBy: [{features.schema.orderBy}!],
+  $after: Cursor
+) {
+  filtered: {features.queries.names.list.field}(
+    filter: $filter
+    orderBy: $orderBy
+    first: 30
+    after: $after
+  ) {
+    totalCount
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+    nodes {
+      ...{features.name}ExplorerProperties
+    }
+  }
+  nonFiltered: {features.queries.names.list.field} {
+    totalCount
+  }
+}
+
+# Subscription (if features.queries.subscription === true)
+subscription {features.namePlural}Mutated {
+  {features.subscriptions.mutated.field} {
+    id
+    eventKey
+    {features.camelCase} {
+      ...{features.name}ExplorerProperties
+    }
+  }
+}
+
+# Filter option queries for each association in selectedFilters
+
+# TagLike associations
+# For each tagLike association in selectedFilters:
+# DO NOT use the helper queries like get{Entity}{Association}Values which return flat string arrays
+query {features.name}{association.label}FilterOptions(
+  $orderBy: [{association.orderByType}!]
+) {
+  {association.connectionField}(orderBy: $orderBy) {
+    nodes {
+      {association.displayField}
+    }
+  }
+}
+
+# ManyToMany associations
+# For each manyToMany association in selectedFilters:
+query {features.name}{association.label}FilterOptions(
+  $orderBy: [{association.relatedOrderByType}!]
+) {
+  {association.relatedQueryField}(orderBy: $orderBy) {
+    nodes {
+      {association.displayField}
+    }
+  }
+}
+
+# Bulk action mutations (if features.mutations.bulkActions === true)
+# Generate for each mutation in features.mutations.names.bulkActions
+# Example for deleteMovies:
+mutation BulkDeleteMovies($filter: MovieFilter) {
+  deleteMovies(filter: $filter) {
+    affectedIds
+  }
+}
+```
+
+## Field Selection Rules
+
+Include in fragment:
+
+- All fields from `selectedColumns`
+- All fields from `selectedFilters`
+- Always: `id`, `titleField`, audit fields (`createdDate`, `updatedDate`)
+
+## Example (Movie entity)
+
+```graphql
+fragment MovieExplorerProperties on Movie {
+  id
+  title
+  originalTitle
+  synopsis
+  released
+  studio
+  # Image capability
+  moviesImages(condition: { imageType: COVER }) {
+    nodes {
+      imageId
+    }
+  }
+  # TagLike association
+  moviesTags {
+    nodes {
+      name
+    }
+  }
+  # ManyToMany association
+  moviesMovieGenres {
+    nodes {
+      movieGenres {
+        title
+      }
+    }
+  }
+  createdDate
+  updatedDate
+}
+
+query Movies($filter: MovieFilter, $orderBy: [MoviesOrderBy!], $after: Cursor) {
+  filtered: movies(
+    filter: $filter
+    orderBy: $orderBy
+    first: 30
+    after: $after
+  ) {
+    totalCount
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+    nodes {
+      ...MovieExplorerProperties
+    }
+  }
+  nonFiltered: movies {
+    totalCount
+  }
+}
+
+subscription MoviesMutated {
+  movieMutated {
+    id
+    eventKey
+    movie {
+      ...MovieExplorerProperties
+    }
+  }
+}
+
+# TagLike filter query
+query MovieTagsFilterOptions($orderBy: [MoviesTagsOrderBy!]) {
+  moviesTags(orderBy: $orderBy) {
+    nodes {
+      name
+    }
+  }
+}
+
+# ManyToMany filter query
+query MovieGenresFilterOptions($orderBy: [MovieGenresOrderBy!]) {
+  movieGenres(orderBy: $orderBy) {
+    nodes {
+      title
+    }
+  }
+}
+
+mutation BulkDeleteMovies($filter: MovieFilter) {
+  deleteMovies(filter: $filter) {
+    affectedIds
+  }
+}
+```
+
+## Notes
+
+- VS Code may briefly show "Syntax Error: Unexpected <EOF>" when creating the
+  GraphQL file. This is a false positive caused by a race condition between file
+  creation and the `Apollo` extension's validation. It auto-resolves within
+  seconds and is safe to ignore and proceed.

package/skills/generate-explorer-station/refs/templates/navigation-explorer-station.md

@@ -0,0 +1,144 @@
+---
+name: navigation-explorer-station
+input:
+  - EntityFeatures
+  - All common files (columns, filters, dataProvider, etc.)
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{EntityPlural}Explorer/{EntityPlural}.tsx'
+    description: 'Main NavigationExplorer station component'
+---
+
+# Generate Main Station
+
+Direct NavigationExplorer component with TODOs for missing features.
+
+## Template
+
+```typescript
+import { NavigationExplorer } from '@axinom/mosaic-ui';
+// If features.mutations.bulkEdit === true:
+import { generateBulkEditMutation } from '@axinom/mosaic-ui';
+import { gql } from 'graphql-tag';
+import { client } from '{discoveredPath}/apolloClient';
+import { {EntityPlural}BulkEdit } from './BulkEdit/{EntityPlural}BulkEdit';
+import { {EntityPlural}BulkEditConfig } from './BulkEdit/{EntityPlural}BulkEditConfig';
+// End if
+
+import React from 'react';
+// If features.mutations.bulkActions === true:
+import { use{EntityPlural}BulkActions } from './common/{EntityPlural}.bulkActions';
+// End if
+import { {entityCamel}Columns } from './common/{EntityPlural}.columns';
+import { create{EntityPlural}DataProvider } from './common/{EntityPlural}.dataProvider';
+import { use{EntityPlural}Filters } from './common/{EntityPlural}.filters';
+import { use{EntityPlural}InlineActions } from './common/{EntityPlural}.inlineActions';
+import { {Entity}Data } from './common/{EntityPlural}.types';
+
+export const {EntityPlural}: React.FC = () => {
+  const { transformFilters, filterOptions } = use{EntityPlural}Filters();
+  // If features.mutations.bulkActions === true:
+  const { bulkActions } = use{EntityPlural}BulkActions();
+  // End if
+  const { generateInlineMenuActions } = use{EntityPlural}InlineActions();
+
+  const dataProvider = create{EntityPlural}DataProvider(transformFilters);
+
+  return (
+    <NavigationExplorer<{Entity}Data>
+      title="{EntityPlural}"
+      stationKey="{EntityPlural}Explorer"
+      // TODO: Update once Details station exists
+      calculateNavigateUrl={(item) => `/{kebabCasePlural}/${item.id}`}
+      // If features.mutations.create === true:
+      // TODO: Update once Create station exists
+      onCreateAction="/{kebabCasePlural}/create"
+      // End if
+      columns={{entityCamel}Columns}
+      dataProvider={dataProvider}
+      filterOptions={filterOptions}
+      defaultSortOrder={{ column: 'updatedDate', direction: 'desc' }}
+      inlineMenuActions={generateInlineMenuActions}
+      // If features.mutations.bulkActions === true:
+      bulkActions={bulkActions}
+      // End if
+      quickEditRegistrations={[
+        // TODO: Add quick edit registrations once Details/Image/Video stations exist
+        // Example structure:
+        // { component: <{Entity}DetailsQuickEdit />, label: '{Entity} Details' },
+        // { component: <{Entity}ImageManagementQuickEdit />, label: 'Manage Images' },
+        // { component: <{Entity}VideoManagementQuickEdit />, label: 'Manage Videos' },
+      ]}
+      // If features.mutations.bulkEdit === true:
+      bulkEditRegistration={{
+        component: <{EntityPlural}BulkEdit />,
+        saveData: async (data, items) => {
+          let filter = undefined as Record<string, unknown> | undefined;
+
+          if (items.mode === 'SINGLE_ITEMS' && items.items && items.items.length > 0) {
+            filter = { id: { in: items.items.map((item) => item.id) } };
+          }
+
+          if (items.mode === 'SELECT_ALL') {
+            filter = transformFilters(items.filters);
+          }
+
+          const mutation = generateBulkEditMutation({EntityPlural}BulkEditConfig, data, filter);
+
+          await client.mutate({ mutation: gql`${mutation}` });
+        },
+      }}
+      // End if
+    />
+  );
+};
+```
+
+## TODOs in Generated Code
+
+1. **calculateNavigateUrl** - Route works but needs verification once Details
+   station exists
+2. **onCreateAction** - Only generated if `features.mutations.create === true`,
+   needs verification once Create station exists
+3. **inlineActions.ts** - Empty array with commented examples (delete/Open
+   Details actions added by build-details skill)
+4. **quickEditRegistrations** - Empty array with commented examples (added when
+   Details/Image/Video stations exist)
+
+## Example (Product - minimal)
+
+```typescript
+import { NavigationExplorer } from '@axinom/mosaic-ui';
+import React from 'react';
+import { productsColumns } from './common/Products.columns';
+import { createProductsDataProvider } from './common/Products.dataProvider';
+import { useProductsFilters } from './common/Products.filters';
+import { useProductsInlineActions } from './common/Products.inlineActions';
+import { ProductData } from './common/Products.types';
+
+export const Products: React.FC = () => {
+  const { transformFilters, filterOptions } = useProductsFilters();
+  const { generateInlineMenuActions } = useProductsInlineActions();
+  const dataProvider = createProductsDataProvider(transformFilters);
+
+  return (
+    <NavigationExplorer<ProductData>
+      title="Products"
+      stationKey="ProductsExplorer"
+      // TODO: Update once Details station exists
+      calculateNavigateUrl={(item) => `/products/${item.id}`}
+      // TODO: Update once Create station exists
+      onCreateAction="/products/create"
+      columns={productsColumns}
+      dataProvider={dataProvider}
+      filterOptions={filterOptions}
+      defaultSortOrder={{ column: 'updatedDate', direction: 'desc' }}
+      inlineMenuActions={generateInlineMenuActions}
+      quickEditRegistrations={
+        [
+          // TODO: Add quick edit registrations once Details/Image/Video stations exist
+        ]
+      }
+    />
+  );
+};
+```