@kosdev-code/kos-nx-plugin 2.1.2 → 2.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kosdev-code/kos-nx-plugin",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "type": "commonjs",
   "generators": "./generators.json",
   "publishConfig": {
@@ -19,7 +19,7 @@
   "main": "./src/index.js",
   "kos": {
     "build": {
-      "gitHash": "ced64602bed23fe8386ffbada4657bec2503a42f"
+      "gitHash": "22bfa6b003918abbc473ab6b5cae1728e473a7e9"
     }
   }
 }

package/src/generators/kos-component/README.md

@@ -33,12 +33,12 @@ Add your new plugin type to `types.ts`:
 // types.ts
 export const PLUGIN_TYPES = {
   // ... existing types
-  MY_NEW_PLUGIN: 'myNewPlugin',
+  MY_NEW_PLUGIN: "myNewPlugin",
 } as const;
 
 export const CONTRIBUTION_TYPE_MAP: Record<string, string> = {
   // ... existing mappings
-  [PLUGIN_TYPES.MY_NEW_PLUGIN]: 'my-new-contribution',
+  [PLUGIN_TYPES.MY_NEW_PLUGIN]: "my-new-contribution",
 };
 
 // Add to localized types if your plugin needs i18n
@@ -53,18 +53,18 @@ export const LOCALIZED_PLUGIN_TYPES: ReadonlySet<string> = new Set([
 Create a new handler file `plugin-handlers/my-new-plugin-handler.ts`:
 
 ```typescript
-import { NormalizedOptions, PluginConfiguration, PLUGIN_TYPES } from '../types';
-import { BasePluginHandler } from './base';
+import { NormalizedOptions, PluginConfiguration, PLUGIN_TYPES } from "../types";
+import { BasePluginHandler } from "./base";
 
 export class MyNewPluginHandler extends BasePluginHandler {
   protected pluginType = PLUGIN_TYPES.MY_NEW_PLUGIN;
-  protected contributionKey = 'my-new-contribution';
+  protected contributionKey = "my-new-contribution";
   protected requiresI18n = true; // or false if no localization needed
-  
+
   createConfiguration(options: NormalizedOptions): PluginConfiguration {
     const configPrefix = this.getConfigPrefix(options);
     const experienceId = `${configPrefix}.myNewPlugin.experience`;
-    
+
     const contribution = {
       id: `${configPrefix}.myNewPlugin`,
       title: `${configPrefix}.myNewPlugin.title`,
@@ -73,9 +73,9 @@ export class MyNewPluginHandler extends BasePluginHandler {
       myCustomProperty: options.nameCamelCase,
       experienceId,
     };
-    
+
     const experience = this.createExperience(options, experienceId);
-    
+
     return {
       contributions: {
         myNewContributions: [contribution], // Use appropriate contribution key
@@ -91,6 +91,7 @@ export class MyNewPluginHandler extends BasePluginHandler {
 #### Handler Customization Options
 
 **Override template path** if your plugin uses custom templates:
+
 ```typescript
 getTemplatePath(): string {
   return 'my-custom-template-folder';
@@ -98,6 +99,7 @@ getTemplatePath(): string {
 ```
 
 **Custom component path** if needed:
+
 ```typescript
 protected getComponentPath(options: NormalizedOptions): string {
   return `${options.appDirectory}/custom-path/${options.nameDashCase}/${options.nameDashCase}.tsx`;
@@ -122,15 +124,15 @@ private static handlers: Map<string, new () => PluginHandler> = new Map<
 ]);
 ```
 
-### 4. Register CLI Command (Required for kosui plugin:* syntax)
+### 4. Register CLI Command (Required for kosui plugin:\* syntax)
 
 To make your plugin available via `kosui plugin:myNewPlugin`, update the CLI metadata in `/packages/sdk/kos-ui-cli/src/lib/generators/plugin/index.mjs`:
 
 ```javascript
 export const metadata = [
   // ... existing metadata
-  { 
-    key: "plugin:myNewPlugin", 
+  {
+    key: "plugin:myNewPlugin",
     name: "KOS UI Plugin My New Plugin",
     namedArguments: {
       name: "componentName",
@@ -138,8 +140,8 @@ export const metadata = [
       project: "componentProject",
       componentProject: "componentProject",
       // Add any plugin-specific arguments
-      customOption: "customOption"
-    }
+      customOption: "customOption",
+    },
   },
 ];
 
@@ -166,6 +168,7 @@ kos-component/
 ```
 
 **Component Template** (`__nameDashCase__.tsx__template__`):
+
 ```typescript
 import React from 'react';
 
@@ -186,12 +189,13 @@ export default <%= namePascalCase %>;
 ```
 
 **Storybook Template** (`__nameDashCase__.stories.tsx__template__`):
+
 ```typescript
 /**
  * Note: The plugin project Storybook configuration requires that the Studio
  * Simulator is running in order to retrieve model data...
  */
-import { MyNewPluginStoryContainer } from "@kosdev-code/kos-ui-plugin/dev";
+import { MyNewPluginStoryContainer } from "@kosdev-code/kos-ui-plugin-dev";
 import type { Meta, StoryObj } from "@storybook/react";
 import { <%= namePascalCase %> } from "./<%= nameDashCase %>";
 
@@ -219,8 +223,9 @@ export const Default: Story = {
 ```
 
 **Available Story Containers:**
+
 - `CUIStoryContainer` - For CUI plugins
-- `UtilityStoryContainer` - For utility plugins  
+- `UtilityStoryContainer` - For utility plugins
 - `SetupStoryContainer` - For setup plugins
 - `SettingStoryContainer` - For setting plugins
 - `NavStoryContainer` - For navigation plugins
@@ -243,6 +248,7 @@ If your plugin needs additional CLI parameters, update `schema.json`:
 ```
 
 And update `schema.d.ts`:
+
 ```typescript
 export interface KosComponentGeneratorSchema {
   // ... existing properties
@@ -260,11 +266,11 @@ export function validateOptions(
   options: KosComponentGeneratorSchema
 ): void {
   // ... existing validation
-  
+
   // Add custom validation for your plugin
-  if (options.pluginType === 'myNewPlugin' && !options.myCustomOption) {
+  if (options.pluginType === "myNewPlugin" && !options.myCustomOption) {
     throw new ValidationError(
-      'myCustomOption is required for myNewPlugin type'
+      "myCustomOption is required for myNewPlugin type"
     );
   }
 }
@@ -273,11 +279,13 @@ export function validateOptions(
 ## Testing Your New Plugin Type
 
 ### 1. Build the Plugin
+
 ```bash
 nx build kos-nx-plugin
 ```
 
 ### 2. Test Generation
+
 ```bash
 # Test your new plugin type using the specific plugin generator
 kosui plugin:myNewPlugin --name test-component --project my-test-project
@@ -288,9 +296,11 @@ kosui pluginComponent --name test-component --project my-test-project
 ```
 
 ### 3. Verify Output
+
 Check that the generated files include:
+
 - Component files in the correct location (`.tsx`)
-- Storybook stories (`.stories.tsx`) 
+- Storybook stories (`.stories.tsx`)
 - Index files (`index.ts`)
 - Updated .kos.json with your contribution
 - Localization entries (if applicable)
@@ -299,12 +309,15 @@ Check that the generated files include:
 ## Best Practices
 
 ### 1. **Naming Conventions**
+
 - Plugin type: `camelCase` (e.g., `myNewPlugin`)
 - Contribution key: `kebab-case` (e.g., `my-new-contribution`)
 - Handler class: `PascalCase` + `Handler` (e.g., `MyNewPluginHandler`)
 
 ### 2. **Configuration Structure**
+
 Follow existing patterns for contribution objects:
+
 ```typescript
 {
   id: `${configPrefix}.${pluginType}`,
@@ -316,11 +329,13 @@ Follow existing patterns for contribution objects:
 ```
 
 ### 3. **Template Organization**
+
 - Use meaningful template folder names
 - Include index.ts for clean imports
 - Follow existing template variable patterns
 
 ### 4. **Documentation**
+
 - Update CLI help text if needed
 - Add examples to this README
 - Document any special requirements
@@ -328,13 +343,14 @@ Follow existing patterns for contribution objects:
 ## Extending Base Functionality
 
 ### Custom Experience Creation
+
 ```typescript
 protected createExperience(
   options: NormalizedOptions,
   experienceId: string
 ): ExperienceConfig {
   const compPath = this.getCustomComponentPath(options);
-  
+
   return {
     id: experienceId,
     component: options.namePascalCase,
@@ -346,11 +362,12 @@ protected createExperience(
 ```
 
 ### Custom Contribution Logic
+
 ```typescript
 createConfiguration(options: NormalizedOptions): PluginConfiguration {
   // Create multiple contributions if needed
   const contributions = this.createMultipleContributions(options);
-  
+
   return {
     contributions: {
       contribution1: contributions.first,
@@ -369,24 +386,24 @@ Here's a complete example for a "dashboard" plugin type:
 // plugin-handlers/dashboard-handler.ts
 export class DashboardPluginHandler extends BasePluginHandler {
   protected pluginType = PLUGIN_TYPES.DASHBOARD;
-  protected contributionKey = 'dashboard';
+  protected contributionKey = "dashboard";
   protected requiresI18n = true;
-  
+
   createConfiguration(options: NormalizedOptions): PluginConfiguration {
     const configPrefix = this.getConfigPrefix(options);
     const experienceId = `${configPrefix}.dashboard.experience`;
-    
+
     const contribution = {
       id: `${configPrefix}.dashboard`,
       title: `${configPrefix}.dashboard.title`,
       namespace: options.appProject,
       dashboardType: options.nameCamelCase,
-      layout: 'grid', // Dashboard-specific property
+      layout: "grid", // Dashboard-specific property
       experienceId,
     };
-    
+
     const experience = this.createExperience(options, experienceId);
-    
+
     return {
       contributions: {
         dashboards: [contribution],
@@ -421,21 +438,25 @@ kosui pluginComponent --name data-export --project admin-ui
 ## Troubleshooting
 
 **Plugin not recognized:**
+
 - Verify handler is registered in factory.ts
 - Check PLUGIN_TYPES constant is exported
 - Ensure plugin type matches exactly
 
 **Template not found:**
+
 - Check template folder name matches contributionKey
 - Verify template files exist and have correct extensions
 - Use `getTemplatePath()` if using custom path
 
 **Configuration not applied:**
+
 - Check .kos.json structure matches expected format
 - Verify contribution keys are correct
 - Test KosConfigBuilder logic with debug output
 
 **Localization not working:**
+
 - Ensure plugin type is in LOCALIZED_PLUGIN_TYPES
 - Check locale file exists at expected path
 - Verify updateLocalization is called for your handler
@@ -450,4 +471,4 @@ When contributing new plugin types to the KOS framework:
 4. Submit PR with clear description of the plugin's purpose
 5. Include usage examples
 
-For questions or support, refer to the KOS development team or create an issue in the project repository.
+For questions or support, refer to the KOS development team or create an issue in the project repository.

package/src/generators/kos-component/control-pour/__nameDashCase__.stories.tsx__template__

@@ -2,7 +2,7 @@
  * Note: The plugin project Storybook configuration requires that the Studio
  * Simulator is running in order to retrieve model data...
  */
-import { ControlPourStoryContainer } from "@kosdev-code/kos-ui-plugin/dev";
+import { ControlPourStoryContainer } from "@kosdev-code/kos-ui-plugin-dev";
 import type { Meta, StoryObj } from "@storybook/react";
 import { <%= namePascalCase %> } from "./<%= nameDashCase %>";
 

package/src/generators/kos-component/cui/__nameDashCase__.stories.tsx__template__

@@ -2,7 +2,7 @@
  * Note: The plugin project Storybook configuration requires that the Studio
  * Simulator is running in order to retrieve model data...
  */
-import { CUIStoryContainer } from "@kosdev-code/kos-ui-plugin/dev";
+import { CUIStoryContainer } from "@kosdev-code/kos-ui-plugin-dev";
 import type { Meta, StoryObj } from "@storybook/react";
 import { <%= namePascalCase %> } from "./<%= nameDashCase %>";
 

package/src/generators/kos-component/custom/__nameDashCase__.stories.tsx__template__

@@ -0,0 +1,31 @@
+import { Button } from '@kosdev-code/kos-ddk-components';
+import { StoryObj } from '@storybook/react';
+import { <%= namePascalCase %> } from './<%= nameDashCase %>';
+
+const meta = {
+  title: '<%= appProject %>/<%= namePascalCase %> Custom Plugin',
+  component: <%= namePascalCase %>,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    onComplete: () => console.log('Custom plugin completed'),
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ padding: '20px' }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const WithCustomAction: Story = {
+  args: {
+    onComplete: () => alert('Custom action triggered!'),
+  },
+};

package/src/generators/kos-component/custom/__nameDashCase__.tsx__template__

@@ -0,0 +1,53 @@
+import styled from '@emotion/styled';
+import {
+  Button,
+  Footer,
+  type Experience,
+} from '@kosdev-code/kos-ddk-components';
+import {
+  KosLog,
+  kosComponent,
+  useKosTranslation,
+} from '@kosdev-code/kos-ui-sdk';
+
+const log = KosLog.createLogger({name: "<%= nameDashCase %>"})
+log.debug("<%= nameDashCase %> component loaded");
+
+const <%= namePascalCase %>Container = styled.div`
+  align-items: center;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+`;
+
+/**
+ * Custom plugin component for <%= contributionKey || 'custom' %> contribution
+ *
+ * TODO: Add additional fields to your .kos.json contribution as required by the plugin-explorer specification.
+ * Refer to the plugin-explorer documentation for your specific contribution type.
+ *
+ * The basic contribution structure has been created, but you may need to add fields such as:
+ * - icon: The icon to display for this contribution
+ * - order: The display order relative to other contributions
+ * - when: Conditional visibility expressions
+ * - category: The category this contribution belongs to
+ * - etc.
+ */
+export const <%= namePascalCase %>: Experience = kosComponent(({ onComplete }) => {
+  const { t } = useKosTranslation('<%= appProject %>');
+
+  return (
+    <<%= namePascalCase %>Container>
+      <h2><%= namePascalCase %> Custom Plugin</h2>
+      <p>This is a custom plugin component with contribution key: <%= contributionKey || 'custom' %></p>
+
+      {/* TODO: Implement your custom plugin functionality here */}
+
+      <Footer>
+        <Button onClick={onComplete}>{t('proceed')}</Button>
+      </Footer>
+    </<%= namePascalCase %>Container>
+  );
+});
+
+export default <%= namePascalCase %>

package/src/generators/kos-component/custom/index.ts__template__

@@ -0,0 +1 @@
+export * from './<%= nameDashCase %>';

package/src/generators/kos-component/generator.d.ts

@@ -1,5 +1,8 @@
 import { Tree } from "@nx/devkit";
 import { KosComponentGeneratorSchema } from "./schema";
+/**
+ * KOS Component Generator
+ */
 export declare function kosComponentGenerator(tree: Tree, options: KosComponentGeneratorSchema): Promise<void>;
 export default kosComponentGenerator;
 //# sourceMappingURL=generator.d.ts.map

package/src/generators/kos-component/generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../../../../../packages/plugins/kos-nx-plugin/src/generators/kos-component/generator.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,IAAI,EAEL,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAmBvD,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,2BAA2B,iBAmUrC;AAED,eAAe,qBAAqB,CAAC"}
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../../../../../../packages/plugins/kos-nx-plugin/src/generators/kos-component/generator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyC,IAAI,EAAE,MAAM,YAAY,CAAC;AAIzE,OAAO,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC;AAQvD;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,2BAA2B,iBAiCrC;AA4FD,eAAe,qBAAqB,CAAC"}