@kosdev-code/kos-nx-plugin 0.1.0-dev.5053

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

@@ -0,0 +1,474 @@
+# Adding New Plugin Component Types
+
+This guide explains how to extend the KOS component generator to support new plugin types for KOS UI applications.
+
+## Overview
+
+The KOS component generator uses a modular architecture where each plugin type is handled by a dedicated handler class. This makes it easy to add new plugin types without modifying the core generator logic.
+
+## Architecture
+
+```
+kos-component/
+├── generator.ts              # Main generator (orchestrates the process)
+├── types.ts                 # Type definitions and constants
+├── plugin-handlers/         # Plugin-specific logic
+│   ├── base.ts             # Base handler interface and common functionality
+│   ├── [type]-handler.ts   # Individual plugin handlers
+│   └── factory.ts          # Handler factory and registry
+└── utils/                   # Shared utilities
+    ├── file-generator.ts    # File generation logic
+    ├── localization.ts      # i18n updates
+    ├── kos-config-builder.ts # .kos.json configuration builder
+    └── validation.ts        # Input validation
+```
+
+## Step-by-Step Guide
+
+### 1. Define Plugin Type Constants
+
+Add your new plugin type to `types.ts`:
+
+```typescript
+// types.ts
+export const PLUGIN_TYPES = {
+  // ... existing types
+  MY_NEW_PLUGIN: "myNewPlugin",
+} as const;
+
+export const CONTRIBUTION_TYPE_MAP: Record<string, string> = {
+  // ... existing mappings
+  [PLUGIN_TYPES.MY_NEW_PLUGIN]: "my-new-contribution",
+};
+
+// Add to localized types if your plugin needs i18n
+export const LOCALIZED_PLUGIN_TYPES: ReadonlySet<string> = new Set([
+  // ... existing types
+  PLUGIN_TYPES.MY_NEW_PLUGIN, // if localization is needed
+]);
+```
+
+### 2. Create Plugin Handler
+
+Create a new handler file `plugin-handlers/my-new-plugin-handler.ts`:
+
+```typescript
+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 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`,
+      namespace: options.appProject,
+      // Add plugin-specific properties here
+      myCustomProperty: options.nameCamelCase,
+      experienceId,
+    };
+
+    const experience = this.createExperience(options, experienceId);
+
+    return {
+      contributions: {
+        myNewContributions: [contribution], // Use appropriate contribution key
+      },
+      experiences: {
+        [experienceId]: experience,
+      },
+    };
+  }
+}
+```
+
+#### Handler Customization Options
+
+**Override template path** if your plugin uses custom templates:
+
+```typescript
+getTemplatePath(): string {
+  return 'my-custom-template-folder';
+}
+```
+
+**Custom component path** if needed:
+
+```typescript
+protected getComponentPath(options: NormalizedOptions): string {
+  return `${options.appDirectory}/custom-path/${options.nameDashCase}/${options.nameDashCase}.tsx`;
+}
+```
+
+### 3. Register Handler in Factory
+
+Update `plugin-handlers/factory.ts`:
+
+```typescript
+// Add import
+import { MyNewPluginHandler } from './my-new-plugin-handler';
+
+// Add to handlers map
+private static handlers: Map<string, new () => PluginHandler> = new Map<
+  string,
+  new () => PluginHandler
+>([
+  // ... existing handlers
+  [PLUGIN_TYPES.MY_NEW_PLUGIN, MyNewPluginHandler],
+]);
+```
+
+### 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",
+    name: "KOS UI Plugin My New Plugin",
+    namedArguments: {
+      name: "componentName",
+      componentName: "componentName",
+      project: "componentProject",
+      componentProject: "componentProject",
+      // Add any plugin-specific arguments
+      customOption: "customOption",
+    },
+  },
+];
+
+// Add to pluginTypes array
+const pluginTypes = [
+  // ... existing types
+  { key: "plugin:myNewPlugin", name: "myNewPlugin" },
+];
+```
+
+**Important:** The `name` field in pluginTypes must match the `pluginType` value used in the NX generator!
+
+### 5. Create Template Files (Optional)
+
+If your plugin needs custom templates, create a template directory:
+
+```
+kos-component/
+└── my-new-contribution/           # Template folder (matches contributionKey)
+    ├── __nameDashCase__.tsx__template__
+    ├── __nameDashCase__.stories.tsx__template__
+    ├── index.ts__template__
+    └── __nameDashCase__.css__template__ (optional)
+```
+
+**Component Template** (`__nameDashCase__.tsx__template__`):
+
+```typescript
+import React from 'react';
+
+interface <%= namePascalCase %>Props {
+  // Add your plugin-specific props
+}
+
+export const <%= namePascalCase %>: React.FC<<%= namePascalCase %>Props> = (props) => {
+  return (
+    <div className="<%= nameDashCase %>">
+      <h2><%= namePascalCase %> Plugin</h2>
+      {/* Your plugin-specific UI */}
+    </div>
+  );
+};
+
+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 type { Meta, StoryObj } from "@storybook/react";
+import { <%= namePascalCase %> } from "./<%= nameDashCase %>";
+
+const meta: Meta<typeof <%= namePascalCase %>> = {
+  args: {},
+  component: <%= namePascalCase %>,
+  decorators: [
+    (Story, context) => (
+      <MyNewPluginStoryContainer>
+        <Story args={{ ...context.args }} />
+      </MyNewPluginStoryContainer>
+    ),
+  ],
+  tags: ["!autodocs"],
+  title: "my-new-plugin/<%= namePascalCase %>",
+};
+
+export default meta;
+
+type Story = StoryObj<typeof <%= namePascalCase %>>;
+
+export const Default: Story = {
+  render: (props) => <<%= namePascalCase %> {...props} />,
+};
+```
+
+**Available Story Containers:**
+
+- `CUIStoryContainer` - For CUI plugins
+- `UtilityStoryContainer` - For utility plugins
+- `SetupStoryContainer` - For setup plugins
+- `SettingStoryContainer` - For setting plugins
+- `NavStoryContainer` - For navigation plugins
+- `ControlPourStoryContainer` - For control pour plugins
+- `TroubleActionStoryContainer` - For trouble action plugins
+
+### 6. Add Schema Support (Optional)
+
+If your plugin needs additional CLI parameters, update `schema.json`:
+
+```json
+{
+  "properties": {
+    "myCustomOption": {
+      "type": "string",
+      "description": "Custom option for my new plugin type"
+    }
+  }
+}
+```
+
+And update `schema.d.ts`:
+
+```typescript
+export interface KosComponentGeneratorSchema {
+  // ... existing properties
+  myCustomOption?: string;
+}
+```
+
+### 7. Add Validation (Optional)
+
+If your plugin has specific validation requirements, update `utils/validation.ts`:
+
+```typescript
+export function validateOptions(
+  tree: Tree,
+  options: KosComponentGeneratorSchema
+): void {
+  // ... existing validation
+
+  // Add custom validation for your plugin
+  if (options.pluginType === "myNewPlugin" && !options.myCustomOption) {
+    throw new ValidationError(
+      "myCustomOption is required for myNewPlugin type"
+    );
+  }
+}
+```
+
+## 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
+
+# Or use the generic pluginComponent generator
+kosui pluginComponent --name test-component --project my-test-project
+# (This will prompt you to select from existing plugin types)
+```
+
+### 3. Verify Output
+
+Check that the generated files include:
+
+- Component files in the correct location (`.tsx`)
+- Storybook stories (`.stories.tsx`)
+- Index files (`index.ts`)
+- Updated .kos.json with your contribution
+- Localization entries (if applicable)
+- Proper template rendering with correct variable substitution
+
+## 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}`,
+  title: `${configPrefix}.${pluginType}.title`,
+  namespace: options.appProject,
+  experienceId, // if using experiences
+  // Plugin-specific properties
+}
+```
+
+### 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
+
+## 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,
+    location: `./src/${compPath}`,
+    // Add custom experience properties
+    customProperty: 'value',
+  };
+}
+```
+
+### Custom Contribution Logic
+
+```typescript
+createConfiguration(options: NormalizedOptions): PluginConfiguration {
+  // Create multiple contributions if needed
+  const contributions = this.createMultipleContributions(options);
+
+  return {
+    contributions: {
+      contribution1: contributions.first,
+      contribution2: contributions.second,
+    },
+    experiences: { /* ... */ },
+  };
+}
+```
+
+## Example: Complete Plugin Implementation
+
+Here's a complete example for a "dashboard" plugin type:
+
+```typescript
+// plugin-handlers/dashboard-handler.ts
+export class DashboardPluginHandler extends BasePluginHandler {
+  protected pluginType = PLUGIN_TYPES.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
+      experienceId,
+    };
+
+    const experience = this.createExperience(options, experienceId);
+
+    return {
+      contributions: {
+        dashboards: [contribution],
+      },
+      experiences: {
+        [experienceId]: experience,
+      },
+    };
+  }
+}
+```
+
+## CLI Usage
+
+Once implemented, your new plugin type will be available via the CLI:
+
+```bash
+# Generate utility plugin component using specific plugin generator
+kosui plugin:utility --name data-export --project admin-ui
+
+# Generate setting plugin with additional group option
+kosui plugin:setting --name user-preferences --project admin-ui --group appearance
+
+# Generate navigation plugin
+kosui plugin:nav --name system-status --project admin-ui
+
+# Alternative: Using generic plugin component generator
+kosui pluginComponent --name data-export --project admin-ui
+# (Will prompt to select from: cui, setup, utility, setting, nav, controlPour)
+```
+
+## 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
+
+## Contributing
+
+When contributing new plugin types to the KOS framework:
+
+1. Follow this guide for implementation
+2. Add comprehensive tests
+3. Update documentation
+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.

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

@@ -0,0 +1,30 @@
+/**
+ * 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 type { Meta, StoryObj } from "@storybook/react";
+import { <%= namePascalCase %> } from "./<%= nameDashCase %>";
+
+const meta: Meta<typeof <%= namePascalCase %>> = {
+  args: {},
+  component: <%= namePascalCase %>,
+  decorators: [
+    (Story, context) => (
+      <ControlPourStoryContainer>
+        <Story args={{ ...context.args }} />
+      </ControlPourStoryContainer>
+    ),
+  ],
+  tags: ["!autodocs"],
+  title: "ControlPour/<%= namePascalCase %>",
+};
+
+export default meta;
+
+type Story = StoryObj<typeof <%= namePascalCase %>>;
+
+export const Default: Story = {
+  render: (props) => <<%= namePascalCase %> {...props} />,
+};
+

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

@@ -0,0 +1,35 @@
+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%;
+`;
+
+export const <%= namePascalCase %>: Experience = kosComponent(({ onComplete }) => {
+  const { t } = useKosTranslation('<%= appProject %>');
+  return (
+    <<%= namePascalCase %>Container onClick={onComplete}>
+      Hello from <%= namePascalCase %> CUI Configuration
+      <Footer>
+        <Button onClick={onComplete}>{t('proceed')}</Button>
+      </Footer>
+    </<%= namePascalCase %>Container>
+  );
+});
+
+export default <%= namePascalCase %>

package/src/generators/kos-component/control-pour/index.ts__template__

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

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

@@ -0,0 +1,30 @@
+/**
+ * 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 type { Meta, StoryObj } from "@storybook/react";
+import { <%= namePascalCase %> } from "./<%= nameDashCase %>";
+
+const meta: Meta<typeof <%= namePascalCase %>> = {
+  args: {},
+  component: <%= namePascalCase %>,
+  decorators: [
+    (Story, context) => (
+      <CUIStoryContainer>
+        <Story args={{ ...context.args }} />
+      </CUIStoryContainer>
+    ),
+  ],
+  tags: ["!autodocs"],
+  title: "CUI/<%= namePascalCase %>",
+};
+
+export default meta;
+
+type Story = StoryObj<typeof <%= namePascalCase %>>;
+
+export const Default: Story = {
+  render: (props) => <<%= namePascalCase %> {...props} />,
+};
+

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

@@ -0,0 +1,35 @@
+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%;
+`;
+
+export const <%= namePascalCase %>: Experience = kosComponent(({ onComplete }) => {
+  const { t } = useKosTranslation('<%= appProject %>');
+  return (
+    <<%= namePascalCase %>Container onClick={onComplete}>
+      Hello from <%= namePascalCase %> CUI Configuration
+      <Footer>
+        <Button onClick={onComplete}>{t('proceed')}</Button>
+      </Footer>
+    </<%= namePascalCase %>Container>
+  );
+});
+
+export default <%= namePascalCase %>

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

@@ -0,0 +1 @@
+export * 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/files/__nameDashCase__.css__template__

@@ -0,0 +1,2 @@
+.<%= nameDashCase %> {
+}