@axinom/mosaic-agent-skills 0.0.1

package/skills/generate-details-station/refs/templates/details-form-station.md

@@ -0,0 +1,589 @@
+---
+name: details-form-station
+input:
+  - EntityFeatures
+  - DiscoveredPaths
+  - Reference: field-component-mapping
+  - Reference: field-validation-schema
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{Entity}Details/{Entity}DetailsForm.tsx'
+    description:
+      'Main form component with query, submit logic, fields, info panel'
+---
+
+# Generate DetailsForm Component
+
+Core details form with data fetching, dynamic mutation building, field
+rendering, and info panel.
+
+## Discovery
+
+**Discover dependencies before generating:**
+
+1. **getEnumLabel** - Search for `getEnumLabel` in `src/Util` or similar
+   - Used for displaying enum fields in info panel
+   - If not found, use inline implementation (see Fallback section)
+
+## Template Structure
+
+The file has these sections:
+
+1. Imports
+2. Validation schema
+3. Main component function
+4. Panel sub-component (info panel)
+5. Form sub-component (fields)
+6. Helper function (createUpdateDto)
+
+## Section 1: Imports
+
+```typescript
+// If ExtensionsContext discovered:
+import { ID } from '@axinom/mosaic-managed-workflow-integration';
+// End if
+import {
+  CheckboxField,
+  createUpdateGQLFragmentGenerator,
+  CustomTagsField,
+  DateTimeTextField,
+  Details,
+  DetailsProps,
+  formatDateTime,
+  generateArrayMutations,
+  getFormDiff,
+  InfoPanel,
+  Paragraph,
+  RadioField,
+  Section,
+  SelectField,
+  SingleLineTextField,
+  TagsField,
+  TextAreaField,
+} from '@axinom/mosaic-ui';
+import { Field, useFormikContext } from 'formik';
+import gql from 'graphql-tag';
+import { ObjectSchemaDefinition } from 'ObjectSchemaDefinition';
+import React, { useCallback, useContext, useMemo } from 'react';
+import * as Yup from 'yup';
+import { client } from '../../../apolloClient';
+// If ExtensionsContext discovered:
+import { ExtensionsContext } from '{discoveredPaths.extensionsContextPath}';
+// End if
+import {
+  {Entity},
+  {Entity}Document,
+  // For each ManyToMany association:
+  {ManyToMany.relatedType},
+  // End for
+  Mutation,
+  // TagLike create/delete mutation arg types:
+  // For each TagLike association:
+  MutationCreate{PascalConnectionField}Args,
+  MutationDelete{PascalConnectionField}Args,
+  // End for
+  // ManyToMany create/delete mutation arg types:
+  // For each ManyToMany association:
+  MutationCreate{PascalJunctionType}Args,
+  MutationDelete{PascalJunctionType}Args,
+  // End for
+  // Search query types for TagLike associations:
+  // For each TagLike association:
+  Search{Entity}{Label}Document,
+  Search{Entity}{Label}Query,
+  Search{Entity}{Label}QueryVariables,
+  // End for
+  Update{Entity}Input,
+  use{Entity}Query,
+} from '../../../generated/graphql';
+// If getEnumLabel discovered:
+import { getEnumLabel } from '{discoveredPath}/StringEnumMapper/StringEnumMapper';
+// End if
+import { use{Entity}DetailsActions } from './{Entity}Details.actions';
+import classes from './{Entity}Details.module.scss'; // Create empty file if needed
+import { {Entity}DetailsFormData } from './{Entity}Details.types';
+```
+
+## Section 2: Validation Schema
+
+Apply validation rules from `field-validation-schema`:
+
+```typescript
+const {entityCamel}DetailSchema = Yup.object<
+  ObjectSchemaDefinition<{Entity}DetailsFormData>
+>({
+  // Generate validation for each scalar field based on `field-validation-schema`
+
+  // Only generate validations for editable fields
+});
+```
+
+## Section 3: Main Component Function
+
+```typescript
+interface {Entity}DetailsFormProps {
+  {entityCamel}Id: number;
+}
+
+export const {Entity}DetailsForm: React.FC<{Entity}DetailsFormProps> = ({
+  {entityCamel}Id,
+}) => {
+  // 3.1: Query hook
+  const { loading, data, error } = use{Entity}Query({
+    client,
+    variables: { id: {entityCamel}Id },
+    fetchPolicy: 'network-only',
+  });
+
+  // 3.2: Data transformation (associations to arrays)
+  const {
+    // For each ManyToMany: all{Label}
+    // For each TagLike: use semantic plural name (see types.md for naming rules)
+    // ManyToMany global data:
+    // For each ManyToMany association:
+    all{Label},
+    // End for
+    // TagLike arrays (semantic plural: tags, cast, productionCountries):
+    // For each TagLike association:
+    {semanticPluralName}, // derived from connection field name
+    // End for
+    // ManyToMany arrays:
+    // For each ManyToMany association:
+    {label.toLowerCase()}, // e.g., genres
+    // End for
+  } = useMemo(
+    () => ({
+      // ManyToMany global data (options for dropdowns):
+      // For each ManyToMany association:
+      all{Label}: data?.{relatedQueryField}?.nodes.reduce<{
+        [key: string]: Partial<{RelatedType}>;
+      }>((result, current) => {
+        result[current.{displayField}] = current;
+        return result;
+      }, {}) ?? {},
+      // End for
+
+      // TagLike association arrays:
+      // For each TagLike association:
+      {semanticPluralName}: data?.{entityCamel}?.{connectionField}.nodes.map(
+        (node) => node.{displayField}
+      ),
+      // End for
+
+      // ManyToMany association arrays:
+      // For each ManyToMany association:
+      {label.toLowerCase()}: data?.{entityCamel}?.{connectionField}.nodes.map(
+        (node) => node.{relatedField}?.{displayField} ?? ''
+      ),
+      // End for
+    }),
+    [data]
+  );
+
+  // 3.3: Actions hook
+  const { actions } = use{Entity}DetailsActions({entityCamel}Id);
+
+  // 3.4: Submit handler (see Section 3.4 below)
+  const onSubmit = useCallback(
+    async (
+      formData: {Entity}DetailsFormData,
+      initialData: DetailsProps<{Entity}DetailsFormData>['initialData']
+    ): Promise<void> => {
+      // Submit logic here...
+    },
+    [
+      // Dependencies: all{Label} for each ManyToMany
+      // For each ManyToMany:
+      all{Label},
+      // End for
+      {entityCamel}Id
+    ]
+  );
+
+  // 3.5: Render Details component
+  return (
+    <Details<{Entity}DetailsFormData>
+      defaultTitle="{Entity}"
+      titleProperty="{titleField}"
+      subtitle="Properties"
+      alwaysShowActionsPanel={true}
+      actions={actions}
+      validationSchema={{entityCamel}DetailSchema}
+      initialData={{
+        data: {
+          ...data?.{entityCamel},
+          // Association arrays:
+          // For each TagLike:
+          {semanticPluralName},
+          // End for
+          // For each ManyToMany:
+          {label.toLowerCase()},
+          // End for
+        },
+        loading,
+        entityNotFound: data?.{entityCamel} === null,
+        error: error?.message,
+      }}
+      saveData={onSubmit}
+      infoPanel={<Panel />}
+    >
+      <Form
+        // For each ManyToMany association:
+        {label.toLowerCase()}Options={Object.keys(all{Label})}
+        // End for
+      />
+    </Details>
+  );
+};
+```
+
+## Section 3.4: Submit Handler (Dynamic Mutations)
+
+```typescript
+const onSubmit = useCallback(
+  async (
+    formData: {Entity}DetailsFormData,
+    initialData: DetailsProps<{Entity}DetailsFormData>['initialData']
+  ): Promise<void> => {
+    const generateUpdateGQLFragment =
+      createUpdateGQLFragmentGenerator<Mutation>();
+
+    // TagLike association mutations:
+    // For each TagLike association:
+    const {semanticPluralName}AssignmentMutations = generateArrayMutations({
+      current: formData.{semanticPluralName},
+      original: initialData.data?.{semanticPluralName},
+      generateCreateMutation: ({displayField}) =>
+        generateUpdateGQLFragment<MutationCreate{PascalConnectionField}Args>(
+          'create{PascalConnectionField}',
+          { input: { {camelConnectionField}: { {displayField}, {entityCamel}Id } } }
+        ),
+      generateDeleteMutation: ({displayField}) =>
+        generateUpdateGQLFragment<MutationDelete{PascalConnectionField}Args>(
+          'delete{PascalConnectionField}',
+          { input: { {entityCamel}Id, {displayField} } }
+        ),
+      prefix: '{camelConnectionField}',
+    });
+    // End for
+
+    // ManyToMany association mutations:
+    // For each ManyToMany association:
+    const {label.toLowerCase()}AssignmentMutations = generateArrayMutations({
+      current: formData.{label.toLowerCase()},
+      original: initialData.data?.{label.toLowerCase()},
+      generateCreateMutation: ({displayField}) => {
+        const {relatedCamel}Id = all{Label}[{displayField}].id;
+
+        if ({relatedCamel}Id) {
+          return generateUpdateGQLFragment<MutationCreate{PascalJunctionType}Args>(
+            'create{PascalJunctionType}',
+            {
+              input: {
+                {camelJunctionType}: {
+                  {entityCamel}Id,
+                  {relatedCamel}Id,
+                },
+              },
+            }
+          );
+        } else {
+          return '';
+        }
+      },
+      generateDeleteMutation: ({displayField}) => {
+        const {relatedCamel}Id = all{Label}[{displayField}].id;
+        if ({relatedCamel}Id) {
+          return generateUpdateGQLFragment<MutationDelete{PascalJunctionType}Args>(
+            'delete{PascalJunctionType}',
+            {
+              input: { {entityCamel}Id, {relatedCamel}Id },
+            }
+          );
+        } else {
+          return '';
+        }
+      },
+      prefix: '{camelJunctionType}',
+    });
+    // End for
+
+    // Create patch (diff of scalar fields only)
+    const patch = createUpdateDto(formData, initialData.data);
+
+    // Build dynamic mutation document
+    const GqlMutationDocument = gql`mutation Update{Entity}($input: Update{Entity}Input!) {
+      update{Entity}(input: $input) {
+        clientMutationId
+        {entityCamel} {
+          id
+          {titleField}
+        }
+      }
+      // For each TagLike:
+      ${{{semanticPluralName}AssignmentMutations}}
+      // End for
+      // For each ManyToMany:
+      ${{{label.toLowerCase()}AssignmentMutations}}
+      // End for
+    }`;
+
+    await client.mutate<unknown, { input: Update{Entity}Input }>({
+      mutation: GqlMutationDocument,
+      variables: { input: { id: {entityCamel}Id, patch } },
+      refetchQueries: [{Entity}Document],
+      awaitRefetchQueries: true,
+    });
+  },
+  [
+    // For each ManyToMany:
+    all{Label},
+    // End for
+    {entityCamel}Id
+  ]
+);
+```
+
+## Section 4: Panel Sub-Component (Info Panel)
+
+```typescript
+const Panel: React.FC = () => {
+  // If ExtensionsContext discovered:
+  const { ImageCover } = useContext(ExtensionsContext);
+  // End if
+  const { values } = useFormikContext<{Entity}>();
+
+  return useMemo(() => {
+    // If features.capabilities.images exists and ExtensionsContext discovered:
+    let coverImageId: ID;
+    let coverImageCount = 0;
+    let teaserImageCount = 0;
+
+    values.{features.capabilities.images.connectionField}?.nodes.forEach(
+      ({ imageId, imageType }) => {
+        switch (imageType) {
+          // For each image type value:
+          case {ImageTypeEnum}.{VALUE}:
+            {value.toLowerCase()}ImageCount++;
+            // If COVER (first value):
+            coverImageId = imageId;
+            // End if
+            break;
+          // End for
+          default:
+            break;
+        }
+      }
+    );
+    // End if
+
+    return (
+      <InfoPanel>
+        // If ExtensionsContext and images capability:
+        <Section>
+          <ImageCover id={coverImageId} />
+        </Section>
+        // End if
+
+        <Section title="Additional Information">
+          <Paragraph title="ID">{values.id}</Paragraph>
+          // For each enum field in features.fields.scalars where type === 'Enum':
+          // Only display enums (already filtered by isMutationControlled during extraction)
+          {values.{enumField} && (
+            <Paragraph title="{Label}">
+              {getEnumLabel(values.{enumField})}
+            </Paragraph>
+          )}
+          // End for
+          <Paragraph title="Created">
+            {formatDateTime(values.createdDate)} by {values.createdUser}
+          </Paragraph>
+          <Paragraph title="Last Modified">
+            {formatDateTime(values.updatedDate)} by {values.updatedUser}
+          </Paragraph>
+        </Section>
+
+        // If features.capabilities exists (videos or images):
+        <Section title="Assigned Items">
+          // If features.capabilities.videos exists:
+          <Paragraph title="Videos">
+            <div className={classes.datalist}>
+              // If mainVideoField exists:
+              <div>Main Video</div>
+              <div className={classes.rightAlignment}>
+                {values.{mainVideoField} ? 1 : 0}/1
+              </div>
+              // End if
+              // If trailersConnection exists:
+              <div>Trailers</div>
+              <div className={classes.rightAlignment}>
+                {values.{trailersConnection}?.totalCount}/many
+              </div>
+              // End if
+            </div>
+          </Paragraph>
+          // End if
+
+          // If features.capabilities.images exists:
+          <Paragraph title="Images">
+            <div className={classes.datalist}>
+              // For each image type value:
+              <div>{Value}</div>
+              <div className={classes.rightAlignment}>
+                {{value.toLowerCase()}ImageCount} / 1
+              </div>
+              // End for
+            </div>
+          </Paragraph>
+          // End if
+        </Section>
+        // End if
+      </InfoPanel>
+    );
+  }, [
+    // If ExtensionsContext:
+    ImageCover,
+    // End if
+    values.createdDate,
+    values.createdUser,
+    values.id,
+    // If videos capability:
+    // If mainVideoField:
+    values.{mainVideoField},
+    // End if
+    // If trailersConnection:
+    values.{trailersConnection}?.totalCount,
+    // End if
+    // End if
+    // If images capability:
+    values.{connectionField}?.nodes,
+    // End if
+    values.updatedDate,
+    values.updatedUser,
+  ]);
+};
+```
+
+## Section 5: Form Sub-Component (Fields)
+
+```typescript
+const Form: React.FC<{
+  // For each ManyToMany:
+  {label.toLowerCase()}Options?: string[];
+  // End for
+}> = ({
+  // For each ManyToMany:
+  {label.toLowerCase()}Options,
+  // End for
+}) => {
+  // TagLike suggestion resolvers:
+  // For each TagLike association:
+  const {semanticPluralName}Resolver = async (
+    value: string
+  ): Promise<(string | null)[]> => {
+    const { data } = await client.query<
+      Search{Entity}{Label}Query,
+      Search{Entity}{Label}QueryVariables
+    >({
+      query: Search{Entity}{Label}Document,
+      variables: { searchKey: value, limit: 10 },
+    });
+    return data.get{PascalConnectionField}Values?.nodes ?? [];
+  };
+  // End for
+
+  return (
+    <>
+      // For each scalar field in features.fields.scalars:
+      // Apply component mapping from `field-component-mapping` based on scalar.type:
+      // - String (short) → SingleLineTextField
+      // - String (long) → TextAreaField (name contains: description, notes, comment, body, content)
+      // - Int/Float → SingleLineTextField with type="number"
+      // - Boolean → CheckboxField or RadioField (AI decides)
+      // - Date → DateTimeTextField with modifyTime={false}
+      // - Datetime → DateTimeTextField
+      // - Enum → SelectField with enum options
+      // End for
+
+      // TagLike associations (autocomplete):
+      // For each TagLike association:
+      <Field
+        name="{semanticPluralName}"
+        label="{tagLike.label}"
+        liveSuggestionsResolver={{semanticPluralName}Resolver}
+        as={CustomTagsField}
+      />
+      // End for
+
+      // ManyToMany associations (predefined options):
+      // For each ManyToMany association:
+      <Field
+        name="{label.toLowerCase()}"
+        label="{manyToMany.label}"
+        tagsOptions={{label.toLowerCase()}Options}
+        as={TagsField}
+      />
+      // End for
+    </>
+  );
+};
+```
+
+## Section 6: Helper Function
+
+```typescript
+function createUpdateDto(
+  currentValues: {Entity}DetailsFormData,
+  initialValues?: {Entity}DetailsFormData | null
+): Partial<{Entity}DetailsFormData> {
+  const {
+    // Remove association arrays from diff:
+    // For each TagLike:
+    {semanticPluralName},
+    // End for
+    // For each ManyToMany:
+    {label.toLowerCase()},
+    // End for
+    ...rest
+  } = getFormDiff(currentValues, initialValues);
+
+  return rest;
+}
+```
+
+## Fallback: getEnumLabel
+
+If `getEnumLabel` not discovered in project, add inline implementation:
+
+```typescript
+/**
+ * Converts SCREAMING_SNAKE_CASE enum values to Title Case
+ * @example "PUBLISH_STATUS" → "Publish Status"
+ */
+const getEnumLabel = (value: string | null | undefined): string => {
+  if (!value) return '';
+  return value
+    .split('_')
+    .map((word) => word.charAt(0) + word.slice(1).toLowerCase())
+    .join(' ');
+};
+```
+
+## CSS Module (minimal)
+
+Create `{Entity}Details.module.scss`:
+
+```scss
+.datalist {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  gap: 0.5rem;
+}
+
+.rightAlignment {
+  text-align: right;
+}
+
+.externalId {
+  grid-column: 1 / -1;
+}
+```

package/skills/generate-details-station/refs/templates/details-wrapper.md

@@ -0,0 +1,54 @@
+---
+name: details-wrapper
+input:
+  - EntityFeatures
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{Entity}Details/{Entity}Details.tsx'
+    description: 'Wrapper component that extracts URL params'
+---
+
+# Generate Router Component
+
+Simple wrapper that extracts URL parameter and delegates to DetailsForm.
+
+## Template
+
+```typescript
+import React from 'react';
+import { useParams } from 'react-router-dom';
+import { {Entity}DetailsForm } from './{Entity}DetailsForm';
+
+interface UrlParams {
+  {entityCamel}Id: string;
+}
+
+export const {Entity}Details: React.FC = () => {
+  const { {entityCamel}Id } = useParams<UrlParams>();
+
+  return <{Entity}DetailsForm {entityCamel}Id={Number({entityCamel}Id)} />;
+};
+```
+
+## Notes
+
+- URL parameter name follows pattern: `{entityCamel}Id`
+- Always converts string param to `Number` (handles UUID if needed in future)
+- Delegates all logic to `{Entity}DetailsForm` component
+
+## Example
+
+```typescript
+import React from 'react';
+import { useParams } from 'react-router-dom';
+import { MovieDetailsForm } from './MovieDetailsForm';
+
+interface UrlParams {
+  movieId: string;
+}
+
+export const MovieDetails: React.FC = () => {
+  const { movieId } = useParams<UrlParams>();
+
+  return <MovieDetailsForm movieId={Number(movieId)} />;
+};
+```

package/skills/generate-details-station/refs/templates/form-data-types.md

@@ -0,0 +1,62 @@
+---
+name: form-data-types
+input:
+  - EntityFeatures
+  - Generated GraphQL types
+output:
+  - path: "{workflowsPath}/src/Stations/{EntityPlural}/{Entity}Details/{Entity}Details.types.ts"
+    description: "Form data type definition"
+---
+
+# Generate types.ts
+
+Form data type extends GraphQL update patch with transformed association arrays.
+
+## Template
+
+```typescript
+import { Nullable } from '@axinom/mosaic-ui';
+import { MutationUpdate{Entity}Args } from '../../../generated/graphql';
+
+export type {Entity}DetailsFormData = Nullable<
+  MutationUpdate{Entity}Args['input']['patch']
+> & {
+  // For each TagLike association, use natural/semantic plural:
+  {semanticPluralName}?: string[];
+
+  // For each ManyToMany association, use lowercase plural of label:
+  {manyToMany.label.toLowerCase()}?: string[];
+};
+```
+
+## Association Field Naming
+
+**TagLike associations:**
+
+Use natural/semantic field names based on the association's meaning:
+- `moviesTags` (displayField: "name") → `tags` (naturally plural)
+- `moviesCasts` (displayField: "name") → `cast` (collective noun, singular)
+- `moviesProductionCountries` (displayField: "name") → `productionCountries` (naturally plural)
+
+Pattern: Derive from connection field name, removing entity prefix and using natural plural form.
+
+**ManyToMany associations:**
+
+- Use lowercase plural form of `label`
+- Examples: `genres`, `categories`, `types`
+
+## Example
+
+```typescript
+import { Nullable } from '@axinom/mosaic-ui';
+import { MutationUpdateMovieArgs } from '../../../generated/graphql';
+
+export type MovieDetailsFormData = Nullable<
+  MutationUpdateMovieArgs['input']['patch']
+> & {
+  tags?: string[];          // from moviesTags
+  genres?: string[];        // from moviesMovieGenres
+  cast?: string[];          // from moviesCasts (collective noun)
+  productionCountries?: string[];  // from moviesProductionCountries
+};
+```