@axinom/mosaic-agent-skills 0.0.1

package/skills/generate-details-station/refs/finalization/explorer-integration.md

@@ -0,0 +1,242 @@
+---
+name: explorer-integration
+input:
+  - EntityFeatures
+  - Generated components (Details, Image Management, Video Management)
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{Entity}Details/{Entity}DetailsQuickEdit.tsx'
+    description: 'Details quick edit component'
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{EntityPlural}Explorer/{EntityPlural}.tsx'
+    description:
+      'Explorer updated with quick edit registrations and inline actions'
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{EntityPlural}Explorer/common/{EntityPlural}.inlineActions.ts'
+    description: 'Inline actions updated with Open Details and Delete actions'
+---
+
+# Integrate Details Station with Explorer
+
+Creates quick edit wrapper components and fully integrates the details station
+with the explorer by updating quick edit registrations, inline actions, and
+navigation URLs.
+
+## Step 1: Generate Details Quick Edit Component
+
+**Path:** `{Entity}Details/{Entity}DetailsQuickEdit.tsx`
+
+```typescript
+import { QuickEditContext, QuickEditContextType } from '@axinom/mosaic-ui';
+import React, { useContext } from 'react';
+import { {Entity}Data } from '../{EntityPlural}Explorer/common/{EntityPlural}.types';
+import { {Entity}DetailsForm } from './{Entity}DetailsForm';
+
+export const {Entity}DetailsQuickEdit: React.FC = () => {
+  const { selectedItem } =
+    useContext<QuickEditContextType<{Entity}Data>>(QuickEditContext);
+
+  return <{Entity}DetailsForm {entityCamel}Id={selectedItem.id} />;
+};
+```
+
+## Step 2: Check if Explorer Exists
+
+**Discovery:** Check if `{EntityPlural}Explorer/{EntityPlural}.tsx` exists
+
+- If **exists** → Proceed to Step 3
+- If **does not exist** → Skip Step 3, move to next step
+
+## Step 3: Integrate with Explorer
+
+**File:** `{EntityPlural}Explorer/{EntityPlural}.tsx`
+
+### 3.1: Add Imports
+
+Add at the top of the file (after existing imports):
+
+```typescript
+import { {Entity}DetailsQuickEdit } from '../{Entity}Details/{Entity}DetailsQuickEdit';
+// If features.capabilities.images exists:
+import { {Entity}ImageManagementQuickEdit } from '../{Entity}ImageManagement/{Entity}ImageManagementQuickEdit';
+// End if
+// If features.capabilities.videos exists:
+import { {Entity}VideoManagementQuickEdit } from '../{Entity}VideoManagement/{Entity}VideoManagementQuickEdit';
+// End if
+```
+
+### 3.2: Update quickEditRegistrations
+
+**Find** the `quickEditRegistrations` prop in the `NavigationExplorer`
+component.
+
+**Replace** the entire prop (including TODO comments) with:
+
+```typescript
+quickEditRegistrations={[
+  { component: <{Entity}DetailsQuickEdit />, label: '{Entity} Details' },
+  // If features.capabilities.images exists:
+  { component: <{Entity}ImageManagementQuickEdit />, label: 'Manage Images' },
+  // End if
+  // If features.capabilities.videos exists:
+  { component: <{Entity}VideoManagementQuickEdit />, label: 'Manage Videos' },
+  // End if
+]}
+```
+
+**Before (with TODOs):**
+
+```typescript
+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' },
+]}
+```
+
+**After (integrated):**
+
+```typescript
+quickEditRegistrations={[
+  { component: <MovieDetailsQuickEdit />, label: 'Movie Details' },
+  { component: <MovieImageManagementQuickEdit />, label: 'Manage Images' },
+  { component: <MovieVideoManagementQuickEdit />, label: 'Manage Videos' },
+]}
+```
+
+### 3.3: Remove calculateNavigateUrl TODO
+
+**Find** the `calculateNavigateUrl` prop.
+
+**Remove** the TODO comment above it (if exists):
+
+```typescript
+// Before:
+// TODO: Update once Details station exists
+calculateNavigateUrl={(item) => `/{kebabCasePlural}/${item.id}`}
+
+// After:
+calculateNavigateUrl={(item) => `/{kebabCasePlural}/${item.id}`}
+```
+
+### 3.4: Update Inline Actions
+
+**File:** `{EntityPlural}Explorer/common/{EntityPlural}.inlineActions.ts`
+
+Once the details station exists with delete mutation, update the inline actions
+to enable "Open Details" navigation and "Delete" actions.
+
+**Add imports** at the top:
+
+```typescript
+import { ActionData, IconName } from '@axinom/mosaic-ui';
+import { client } from '{apolloClientPath}';
+import { useDelete{Entity}Mutation } from '../../../../generated/graphql';
+import { {Entity}Data } from './{EntityPlural}.types';
+```
+
+**Replace** the TODO placeholders in the hook with actual implementations:
+
+```typescript
+export function use{EntityPlural}InlineActions(): {
+  readonly generateInlineMenuActions: (data: {Entity}Data) => ActionData[];
+} {
+  const [delete{Entity}Mutation] = useDelete{Entity}Mutation({
+    client,
+    fetchPolicy: 'no-cache',
+  });
+
+  const generateInlineMenuActions = ({ id }: {Entity}Data): ActionData[] => {
+    return [
+      {
+        label: 'Open Details',
+        path: `/{kebabCasePlural}/${id}`,
+      },
+      {
+        label: 'Delete',
+        onActionSelected: async () => {
+          await delete{Entity}Mutation({ variables: { input: { id } } });
+        },
+        icon: IconName.Delete,
+        confirmationMode: 'Simple',
+      },
+    ];
+  };
+
+  return { generateInlineMenuActions };
+}
+```
+
+## Example (Complete Integration)
+
+**MovieDetailsQuickEdit.tsx:**
+
+```typescript
+import { QuickEditContext, QuickEditContextType } from '@axinom/mosaic-ui';
+import React, { useContext } from 'react';
+import { MovieData } from '../MoviesExplorer/common/Movies.types';
+import { MovieDetailsForm } from './MovieDetailsForm';
+
+export const MovieDetailsQuickEdit: React.FC = () => {
+  const { selectedItem } =
+    useContext<QuickEditContextType<MovieData>>(QuickEditContext);
+
+  return <MovieDetailsForm movieId={selectedItem.id} />;
+};
+```
+
+**Movies.tsx (Explorer) - Updated:**
+
+```typescript
+import { NavigationExplorer } from '@axinom/mosaic-ui';
+import React from 'react';
+import { MovieDetailsQuickEdit } from '../MovieDetails/MovieDetailsQuickEdit';
+import { MovieImageManagementQuickEdit } from '../MovieImageManagement/MovieImageManagementQuickEdit';
+import { MovieVideoManagementQuickEdit } from '../MovieVideoManagement/MovieVideoManagementQuickEdit';
+import { useMoviesBulkActions } from './common/Movies.bulkActions';
+import { moviesColumns } from './common/Movies.columns';
+import { createMoviesDataProvider } from './common/Movies.dataProvider';
+import { useMoviesFilters } from './common/Movies.filters';
+import { useMoviesInlineActions } from './common/Movies.inlineActions';
+import { MovieData } from './common/Movies.types';
+
+export const Movies: React.FC = () => {
+  const { transformFilters, filterOptions } = useMoviesFilters();
+  const { bulkActions } = useMoviesBulkActions();
+  const { generateInlineMenuActions } = useMoviesInlineActions();
+  const dataProvider = createMoviesDataProvider(transformFilters);
+
+  return (
+    <NavigationExplorer<MovieData>
+      title="Movies"
+      stationKey="MoviesExplorer"
+      calculateNavigateUrl={(item) => `/movies/${item.id}`}
+      onCreateAction="/movies/create"
+      columns={moviesColumns}
+      dataProvider={dataProvider}
+      filterOptions={filterOptions}
+      defaultSortOrder={{ column: 'updatedDate', direction: 'desc' }}
+      inlineMenuActions={generateInlineMenuActions}
+      bulkActions={bulkActions}
+      quickEditRegistrations={[
+        { component: <MovieDetailsQuickEdit />, label: 'Movie Details' },
+        {
+          component: <MovieImageManagementQuickEdit />,
+          label: 'Manage Images',
+        },
+        {
+          component: <MovieVideoManagementQuickEdit />,
+          label: 'Manage Videos',
+        },
+      ]}
+    />
+  );
+};
+```
+
+## Notes
+
+- Quick edit components reuse the same form components as full-page views
+- Explorer must exist for integration; if not found, only generate the component
+- All quick edit components follow same pattern (context → extract ID → render
+  form)
+- Quick edit registrations appear in order: Details, Images, Videos

package/skills/generate-details-station/refs/finalization/station-registration.md

@@ -0,0 +1,139 @@
+---
+name: station-registration
+input:
+  - EntityFeatures
+  - Generated components
+  - DiscoveredPaths
+output:
+  - Updated registrations.tsx with details routes
+---
+
+# Register Details Station
+
+Update entity registrations file with details, image management, and video
+management routes.
+
+## File Path
+
+`{workflowsPath}/src/Stations/{EntityPlural}/registrations.tsx`
+
+## Add Imports
+
+```typescript
+import { {Entity}Details } from './{Entity}Details/{Entity}Details';
+import { {Entity}DetailsCrumb } from './{Entity}Details/{Entity}DetailsCrumb';
+// If features.capabilities.images exists:
+import { {Entity}ImageManagement } from './{Entity}ImageManagement/{Entity}ImageManagement';
+// End if
+// If features.capabilities.videos exists:
+import { {Entity}VideoManagement } from './{Entity}VideoManagement/{Entity}VideoManagement';
+// End if
+```
+
+## Add Route Registrations
+
+Add inside the `register()` function:
+
+```typescript
+// Details route
+app.registerPage(
+  '/{kebabCasePlural}/:{entityCamel}Id',
+  () => (
+    <ExtensionsContext.Provider value={extensions}>
+      <{Entity}Details />
+    </ExtensionsContext.Provider>
+  ),
+  {
+    breadcrumb: {Entity}DetailsCrumb,
+    permissions: { '{features.service.serviceId}': {features.service.permissions} },
+  },
+);
+
+// If features.capabilities.images exists:
+// Image management route
+app.registerPage(
+  '/{kebabCasePlural}/:{entityCamel}Id/images',
+  () => (
+    <ExtensionsContext.Provider value={extensions}>
+      <{Entity}ImageManagement />
+    </ExtensionsContext.Provider>
+  ),
+  {
+    breadcrumb: () => 'Manage Images',
+    permissions: { '{features.service.serviceId}': {features.service.permissions} },
+  },
+);
+// End if
+
+// If features.capabilities.videos exists:
+// Video management route
+app.registerPage(
+  '/{kebabCasePlural}/:{entityCamel}Id/videos',
+  () => (
+    <ExtensionsContext.Provider value={extensions}>
+      <{Entity}VideoManagement />
+    </ExtensionsContext.Provider>
+  ),
+  {
+    breadcrumb: () => 'Manage Videos',
+    permissions: { '{features.service.serviceId}': {features.service.permissions} },
+  },
+);
+// End if
+```
+
+## Example
+
+```typescript
+// In registrations.tsx
+import { MovieDetails } from './MovieDetails/MovieDetails';
+import { MovieDetailsCrumb } from './MovieDetails/MovieDetailsCrumb';
+import { MovieImageManagement } from './MovieImageManagement/MovieImageManagement';
+import { MovieVideoManagement } from './MovieVideoManagement/MovieVideoManagement';
+
+export function register(app: PiletApi, extensions: Extensions): void {
+  // ... existing explorer registration ...
+
+  // Details route
+  app.registerPage(
+    '/movies/:movieId',
+    () => (
+      <ExtensionsContext.Provider value={extensions}>
+        <MovieDetails />
+      </ExtensionsContext.Provider>
+    ),
+    {
+      breadcrumb: MovieDetailsCrumb,
+      permissions: { 'media-service': ['ADMIN', 'MOVIES_EDIT', 'MOVIES_VIEW'] },
+    },
+  );
+
+  // Image management route
+  app.registerPage(
+    '/movies/:movieId/images',
+    () => (
+      <ExtensionsContext.Provider value={extensions}>
+        <MovieImageManagement />
+      </ExtensionsContext.Provider>
+    ),
+    {
+      breadcrumb: () => 'Manage Images',
+      permissions: { 'media-service': ['ADMIN', 'MOVIES_EDIT', 'MOVIES_VIEW'] },
+    },
+  );
+
+  // Video management route
+  app.registerPage(
+    '/movies/:movieId/videos',
+    () => (
+      <ExtensionsContext.Provider value={extensions}>
+        <MovieVideoManagement />
+      </ExtensionsContext.Provider>
+    ),
+    {
+      breadcrumb: () => 'Manage Videos',
+      permissions: { 'media-service': ['ADMIN', 'MOVIES_EDIT', 'MOVIES_VIEW'] },
+    },
+  );
+}
+```

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

@@ -0,0 +1,127 @@
+---
+name: details-actions
+input:
+  - EntityFeatures
+  - DiscoveredPaths
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{Entity}Details/{Entity}Details.actions.ts'
+    description: 'Actions hook with navigation and mutation actions'
+---
+
+# Generate Actions Hook
+
+Provides action buttons for details form (delete, navigate to child resources).
+
+## Template
+
+```typescript
+import { FormActionData } from '@axinom/mosaic-ui';
+import { useHistory } from 'react-router';
+import { client } from '../../../apolloClient';
+import {
+  // If features.mutations.delete === true:
+  useDelete{Entity}Mutation,
+  // End if
+} from '../../../generated/graphql';
+import { {Entity}DetailsFormData } from './{Entity}Details.types';
+
+export function use{Entity}DetailsActions(id: number): {
+  readonly actions: FormActionData<{Entity}DetailsFormData}[];
+} {
+  const history = useHistory();
+  // If features.mutations.delete === true:
+  const [delete{Entity}Mutation] = useDelete{Entity}Mutation({
+    client,
+    fetchPolicy: 'no-cache',
+  });
+
+  const delete{Entity} = async (): Promise<void> => {
+    await delete{Entity}Mutation({ variables: { input: { id } } });
+    history.push('/{kebabCasePlural}');
+  };
+  // End if
+
+  const actions: FormActionData<{Entity}DetailsFormData}[] = [
+    // If features.capabilities.videos exists:
+    {
+      label: 'Manage Videos',
+      path: `/{kebabCasePlural}/${id}/videos`,
+    },
+    // End if
+
+    // If features.capabilities.images exists:
+    {
+      label: 'Manage Images',
+      path: `/{kebabCasePlural}/${id}/images`,
+    },
+    // End if
+
+    // If features.mutations.delete === true:
+    {
+      label: 'Delete',
+      confirmationMode: 'Simple' as const,
+      onActionSelected: delete{Entity},
+    },
+    // End if
+  ];
+
+  return { actions } as const;
+}
+```
+
+## Action Types
+
+**Navigation Actions** (`path` property):
+
+- Manage Videos (if `features.capabilities.videos` exists)
+- Manage Images (if `features.capabilities.images` exists)
+
+**Mutation Actions** (`onActionSelected` property):
+
+- Delete (if `features.mutations.delete === true`)
+  - Requires `confirmationMode: 'Simple'`
+  - Navigates to list view after successful deletion
+
+## Example
+
+```typescript
+import { FormActionData } from '@axinom/mosaic-ui';
+import { useHistory } from 'react-router';
+import { client } from '../../../apolloClient';
+import { useDeleteMovieMutation } from '../../../generated/graphql';
+import { MovieDetailsFormData } from './MovieDetails.types';
+
+export function useMovieDetailsActions(id: number): {
+  readonly actions: FormActionData<MovieDetailsFormData>[];
+} {
+  const history = useHistory();
+
+  const [deleteMovieMutation] = useDeleteMovieMutation({
+    client,
+    fetchPolicy: 'no-cache',
+  });
+
+  const deleteMovie = async (): Promise<void> => {
+    await deleteMovieMutation({ variables: { input: { id } } });
+    history.push('/movies');
+  };
+
+  const actions: FormActionData<MovieDetailsFormData>[] = [
+    {
+      label: 'Manage Videos',
+      path: `/movies/${id}/videos`,
+    },
+    {
+      label: 'Manage Images',
+      path: `/movies/${id}/images`,
+    },
+    {
+      label: 'Delete',
+      confirmationMode: 'Simple' as const,
+      onActionSelected: deleteMovie,
+    },
+  ];
+
+  return { actions } as const;
+}
+```

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

@@ -0,0 +1,67 @@
+---
+name: details-breadcrumb
+input:
+  - EntityFeatures
+output:
+  - path: '{workflowsPath}/src/Stations/{EntityPlural}/{Entity}Details/{Entity}DetailsCrumb.tsx'
+    description: 'Async breadcrumb resolver'
+---
+
+# Generate Breadcrumb Resolver
+
+Fetches entity title for breadcrumb display.
+
+## Template
+
+```typescript
+import { BreadcrumbResolver } from '@axinom/mosaic-portal';
+import { client } from '../../../apolloClient';
+import {
+  {Entity}TitleDocument,
+  {Entity}TitleQuery,
+} from '../../../generated/graphql';
+
+export const {Entity}DetailsCrumb: BreadcrumbResolver = (params) => {
+  return async (): Promise<string> => {
+    const response = await client.query<{Entity}TitleQuery>({
+      query: {Entity}TitleDocument,
+      variables: {
+        id: Number(params['{entityCamel}Id']),
+      },
+      errorPolicy: 'ignore',
+    });
+    return response.data.{entityCamel}?.{titleField} ?? '{Entity} Details';
+  };
+};
+```
+
+## Notes
+
+- Extracts `{entityCamel}Id` from route params
+- Queries `{titleField}` from entity
+- Falls back to `'{Entity} Details'` if entity not found
+- Uses `errorPolicy: 'ignore'` to handle deleted/missing entities gracefully
+
+## Example
+
+```typescript
+import { BreadcrumbResolver } from '@axinom/mosaic-portal';
+import { client } from '../../../apolloClient';
+import {
+  MovieTitleDocument,
+  MovieTitleQuery,
+} from '../../../generated/graphql';
+
+export const MovieDetailsCrumb: BreadcrumbResolver = (params) => {
+  return async (): Promise<string> => {
+    const response = await client.query<MovieTitleQuery>({
+      query: MovieTitleDocument,
+      variables: {
+        id: Number(params['movieId']),
+      },
+      errorPolicy: 'ignore',
+    });
+    return response.data.movie?.title ?? 'Movie Details';
+  };
+};
+```