@fishawack/lab-env 4.45.0-beta.2 → 4.45.0-beta.3

package/_Ai/ui-framework-3.md

@@ -0,0 +1,422 @@
+---
+applyTo: "**/*.vue"
+---
+
+# Element Plus UI Framework Integration Instructions for GitHub Copilot
+
+## Project Overview
+
+Element Plus serves as the primary UI component framework, integrated with Vue.js 3 through a structured plugin system. Element Plus provides robust form components, navigation elements, and interactive UI components that are globally registered and customized through SASS overrides. The integration follows a clear separation between JavaScript component registration and SASS styling, maintaining optimal build performance and consistent theming.
+
+Element Plus components are selectively imported and registered globally, with custom styling applied through dedicated SASS override files that layer on top of the built-in Element Plus theme-chalk styles.
+
+## Integration Architecture
+
+### Project Structure Variations
+
+**Important**: Build file locations vary by project configuration. Common patterns include:
+
+- `resources/` directory
+- `_Build/` directory (most common)
+- Custom directory structures as defined in project setup
+
+Always check your project's specific directory structure. File paths in these examples use `[build-dir]` placeholder but should be adapted to your project's build directory.
+
+### JavaScript Registration (`[build-dir]/js/libs/elements.js`)
+
+Element Plus components are registered through a dedicated Vue plugin:
+
+```javascript
+import {
+    ElCheckbox,
+    ElSelect,
+    ElOption,
+    ElInfiniteScroll,
+    ElPopover,
+    ElMenu,
+    ElSubMenu,
+    ElMenuItem,
+} from "element-plus";
+
+export default {
+    install(Vue) {
+        Vue.component(ElCheckbox.name, ElCheckbox);
+        Vue.component(ElSelect.name, ElSelect);
+        Vue.component(ElOption.name, ElOption);
+        Vue.component(ElPopover.name, ElPopover);
+        Vue.component(ElMenu.name, ElMenu);
+        Vue.component(ElSubMenu.name, ElSubMenu);
+        Vue.component(ElMenuItem.name, ElMenuItem);
+
+        Vue.use(ElInfiniteScroll);
+    },
+};
+```
+
+### Plugin Integration (`[build-dir]/js/script.js`)
+
+The Element Plus plugin is registered in the main Vue application:
+
+```javascript
+import elements from "./libs/elements";
+
+const vue = createApp({
+    // App configuration
+});
+
+vue.use(elements);
+vue.mount("#app");
+```
+
+### SASS Integration (`[build-dir]/sass/vendor.scss`)
+
+Element Plus styles are imported selectively in the vendor SASS file:
+
+```scss
+/* purgecss start ignore */
+@import "element-plus/theme-chalk/base";
+
+@import "element-plus/theme-chalk/el-input";
+@import "element-plus/theme-chalk/el-tag";
+@import "element-plus/theme-chalk/el-checkbox";
+@import "element-plus/theme-chalk/el-scrollbar";
+@import "element-plus/theme-chalk/el-select";
+@import "element-plus/theme-chalk/el-option";
+@import "element-plus/theme-chalk/el-option-group";
+@import "element-plus/theme-chalk/el-popover";
+@import "element-plus/theme-chalk/el-popper";
+@import "element-plus/theme-chalk/el-dropdown";
+@import "element-plus/theme-chalk/el-menu";
+/* purgecss end ignore */
+```
+
+## Component Selection and Documentation
+
+### Element Plus Documentation
+
+Reference the official Element Plus documentation for component options and slots:
+
+- **Documentation**: https://element-plus.org/en-US/component/overview.html
+- **Version**: Always assume latest version
+- **Evaluation Process**: Browse the component library and select components based on project needs
+
+### Common Components by Category
+
+#### Form Components (Most Frequently Used):
+
+- `ElCheckbox` - Checkbox inputs with group support
+- `ElSelect` / `ElOption` - Dropdown select components
+- `ElInput` - Text input fields
+- `ElTag` - Tag/chip components for selections
+
+#### Navigation Components:
+
+- `ElMenu` / `ElSubMenu` / `ElMenuItem` - Navigation menu systems
+- `ElDropdown` - Dropdown menu actions
+
+#### Overlay Components:
+
+- `ElPopover` - Tooltip and popover overlays
+- `ElPopper` - Positioning engine for overlays
+
+#### Utility Components:
+
+- `ElScrollbar` - Custom scrollbar styling
+- `ElInfiniteScroll` - Infinite scroll directive
+
+## Adding New Element Plus Components
+
+### Step 1: JavaScript Registration
+
+Add the component import and registration to `[build-dir]/js/libs/elements.js`:
+
+```javascript
+import {
+    // Existing imports
+    ElButton, // New component
+} from "element-plus";
+
+export default {
+    install(Vue) {
+        // Existing registrations
+        Vue.component(ElButton.name, ElButton); // New registration
+    },
+};
+```
+
+### Step 2: SASS Import
+
+Add the corresponding SASS import to `[build-dir]/sass/vendor.scss`:
+
+```scss
+/* purgecss start ignore */
+@import "element-plus/theme-chalk/base";
+
+// Existing imports
+@import "element-plus/theme-chalk/el-button"; // New import
+
+/* purgecss end ignore */
+```
+
+### Step 3: Custom Styling (Optional)
+
+For component-specific styling overrides, add styles to `[build-dir]/sass/components/_element.scss` or create individual override files for larger projects:
+
+**Single File Approach:**
+
+```scss
+// [build-dir]/sass/components/_element.scss
+.el-button {
+    border-radius: 4px;
+    font-weight: $fontWeightMedium;
+
+    &--primary {
+        background-color: $color1;
+        border-color: $color1;
+    }
+}
+```
+
+**Individual File Approach (Larger Projects):**
+
+```scss
+// [build-dir]/sass/components/_el-button.scss
+.el-button {
+    border-radius: 4px;
+    font-weight: $fontWeightMedium;
+
+    &--primary {
+        background-color: $color1;
+        border-color: $color1;
+    }
+
+    &--secondary {
+        background-color: transparent;
+        border-color: $color2;
+        color: $color2;
+    }
+}
+```
+
+Then import in `[build-dir]/sass/general.scss`:
+
+```scss
+@import "./components/_el-button.scss";
+```
+
+## Vue Template Usage
+
+### Basic Component Usage
+
+Once registered globally, Element Plus components are available in all Vue templates:
+
+```vue
+<template>
+    <div class="form-container">
+        <!-- Select dropdown -->
+        <el-select
+            v-model="selectedValue"
+            placeholder="Select an option"
+            class="form__select"
+        >
+            <el-option
+                v-for="item in options"
+                :key="item.value"
+                :label="item.label"
+                :value="item.value"
+            />
+        </el-select>
+
+        <!-- Checkbox -->
+        <el-checkbox v-model="isChecked" class="form__checkbox">
+            Enable notifications
+        </el-checkbox>
+
+        <!-- Menu navigation -->
+        <el-menu mode="horizontal" class="navigation">
+            <el-menu-item index="1">Dashboard</el-menu-item>
+            <el-sub-menu index="2">
+                <template #title>Reports</template>
+                <el-menu-item index="2-1">Analytics</el-menu-item>
+                <el-menu-item index="2-2">Performance</el-menu-item>
+            </el-sub-menu>
+        </el-menu>
+
+        <!-- Popover tooltip -->
+        <el-popover
+            placement="top"
+            title="Help Information"
+            :width="200"
+            trigger="hover"
+            content="This provides additional context about the feature."
+        >
+            <template #reference>
+                <el-button>Hover for info</el-button>
+            </template>
+        </el-popover>
+    </div>
+</template>
+```
+
+### Custom Class Integration
+
+Combine Element Plus components with project BEM classes and lab-ui utilities:
+
+```vue
+<template>
+    <div class="user-form user-form--compact">
+        <div class="user-form__field">
+            <el-select
+                v-model="user.role"
+                class="user-form__select form__group--seamless"
+                placeholder="Select role"
+            >
+                <el-option label="Admin" value="admin" />
+                <el-option label="User" value="user" />
+            </el-select>
+        </div>
+
+        <div class="user-form__actions flex justify-end mt-2">
+            <el-button
+                type="primary"
+                class="user-form__submit"
+                @click="handleSubmit"
+            >
+                Save User
+            </el-button>
+        </div>
+    </div>
+</template>
+```
+
+## Styling Integration
+
+### Theme Integration
+
+Element Plus uses CSS variables for theming, but the typical approach is to layer custom SASS variables and overrides:
+
+```scss
+// Override Element Plus component styles
+.el-input__inner {
+    border: none !important;
+    box-shadow: none !important;
+    min-height: 48px;
+}
+
+.el-select {
+    .el-input__inner {
+        padding: $spacing * 0.5;
+    }
+}
+
+// Custom form variants using project variables
+.form__group--seamless {
+    .el-input__wrapper {
+        --el-select-input-focus-border-color: none;
+        --el-border-color: none;
+        --el-input-border-color: none;
+        --el-input-hover-border-color: none;
+        --el-select-border-color-hover: none;
+    }
+
+    .el-input__inner {
+        padding: 0;
+        height: auto !important;
+        min-height: auto !important;
+        line-height: 1;
+        min-width: auto !important;
+        width: 95px !important;
+    }
+}
+```
+
+### Color System Integration
+
+Use project color variables to maintain consistency with lab-ui:
+
+```scss
+.el-button--primary {
+    background-color: $color1;
+    border-color: $color1;
+
+    &:hover {
+        background-color: $color2;
+        border-color: $color2;
+    }
+}
+
+.el-popover__title {
+    margin-bottom: $spacing * 0.5;
+    color: $color8;
+}
+
+.el-popover.el-popper {
+    color: $fontColor;
+    padding: $spacing;
+    word-break: break-word;
+    text-align: left;
+}
+```
+
+## Development Workflow
+
+### Adding New Components
+
+1. **Research Component**: Visit https://element-plus.org/en-US/component/overview.html
+2. **Evaluate Options**: Review props, slots, and events available
+3. **Register JavaScript**: Add import and registration to `elements.js`
+4. **Import SASS**: Add theme-chalk import to `vendor.scss`
+5. **Test Integration**: Verify component works in Vue templates
+6. **Add Custom Styles**: Create overrides in `_element.scss` or individual files
+7. **Document Usage**: Update component documentation if needed
+
+### Performance Considerations
+
+- **Selective Imports**: Only import components that are actually used
+- **PurgeCSS Protection**: Element Plus styles are wrapped in `/* purgecss start ignore */`
+- **Build Optimization**: Vendor SASS file is cached for faster rebuilds
+- **Tree Shaking**: Unused Element Plus components are automatically excluded
+
+### File Organization
+
+**Small to Medium Projects:**
+
+- Single override file: `[build-dir]/sass/components/_element.scss`
+- All Element Plus customizations in one location
+
+**Large Projects:**
+
+- Individual override files: `[build-dir]/sass/components/_el-[component].scss`
+- Better organization and maintainability
+- Easier to track component-specific changes
+
+## Best Practices
+
+### Component Registration
+
+- Always register components globally for consistency
+- Use the component's default name (`ElButton.name`)
+- Group related components together in imports
+
+### Styling Approach
+
+- Layer custom styles over Element Plus defaults
+- Use project SASS variables for consistent theming
+- Prefer CSS custom properties for dynamic theming
+- Avoid `!important` unless necessary for specificity
+
+### Vue Template Usage
+
+- Combine Element Plus classes with project BEM classes
+- Use semantic prop names and clear component structure
+- Leverage slots for flexible content composition
+- Test responsive behavior across breakpoints
+
+### Maintenance
+
+- Keep Element Plus version updated to latest
+- Review breaking changes in Element Plus updates
+- Test custom overrides after version updates
+- Document any component-specific customizations
+
+Remember: Element Plus provides the foundation UI components, while project-specific styling and behavior are layered on top through the structured SASS architecture and custom component classes.

package/_Ai/workspace-@.md

@@ -0,0 +1,11 @@
+---
+applyTo: "**/*"
+---
+
+# GitHub Copilot Instructions for this workspace
+
+Backends are typically named with the pattern \*-api.
+
+Frontends are typically named with the pattern \*-fe. or with no suffix.
+
+Ensure you cd into the correct directory before running any terminal commands.

package/cli.js

@@ -36,7 +36,15 @@ const args = hideBin(process.argv);
         // Platform command mapping
         const platformCommands = {
             // Base commands available to all platforms
-            base: ["start", "setup", "connect", "execute", "nuke", "lint"],
+            base: [
+                "start",
+                "setup",
+                "connect",
+                "execute",
+                "nuke",
+                "lint",
+                "workspace",
+            ],
 
             // Web development commands (for frameworks that build frontend assets)
             webDev: [

package/commands/workspace.js

@@ -0,0 +1,124 @@
+const _ = require("../globals.js");
+const fs = require("fs");
+const path = require("path");
+const glob = require("glob");
+const { execSync } = require("child_process");
+
+// Helper functions
+const exitWithError = (message) => {
+    console.error(`Error: ${message}`);
+    process.exit(1);
+};
+
+const createSymlink = (sourcePath, targetPath) => {
+    if (fs.existsSync(targetPath)) fs.unlinkSync(targetPath);
+    fs.symlinkSync(
+        path.relative(path.dirname(targetPath), sourcePath),
+        targetPath,
+    );
+};
+
+const generateWorkspaceName = (projects, customName) => {
+    if (customName) return `workspace-${customName}`;
+
+    const firstProject = projects[0];
+    const parts = firstProject.split("-");
+    const baseName =
+        parts.length >= 2 ? parts.slice(0, -1).join("-") : firstProject;
+    return `workspace-${baseName}`;
+};
+
+module.exports = [
+    "workspace <projects..>",
+    "creates workspace directory with project symlinks and AI instruction files",
+    (yargs) => {
+        yargs
+            .positional("projects", {
+                describe: "project directory names to include in workspace",
+                type: "array",
+                demandOption: true,
+            })
+            .option("name", {
+                alias: "n",
+                describe:
+                    "custom workspace name (will be prefixed with 'workspace-')",
+                type: "string",
+            });
+    },
+    (argv) => {
+        const { projects, name } = argv;
+        const cwd = process.cwd();
+
+        // Validation
+        if (!projects?.length)
+            exitWithError("At least one project name is required");
+
+        const missingProjects = projects.filter(
+            (project) => !fs.existsSync(path.join(cwd, project)),
+        );
+        if (missingProjects.length)
+            exitWithError(
+                `Project directories not found: ${missingProjects.join(", ")}`,
+            );
+
+        // Setup workspace
+        const workspaceName = generateWorkspaceName(projects, name);
+        const workspaceDir = path.join(cwd, workspaceName);
+
+        if (fs.existsSync(workspaceDir))
+            exitWithError(
+                `Workspace directory '${workspaceName}' already exists`,
+            );
+
+        fs.mkdirSync(workspaceDir);
+        console.log(`Created workspace directory: ${workspaceName}`);
+
+        // Create project symlinks
+        projects.forEach((project) => {
+            createSymlink(
+                path.join(cwd, project),
+                path.join(workspaceDir, project),
+            );
+            console.log(`Linked project: ${project}`);
+        });
+
+        // Setup AI instructions
+        const instructionsDir = path.join(
+            workspaceDir,
+            ".github",
+            "instructions",
+        );
+        fs.mkdirSync(instructionsDir, { recursive: true });
+
+        const instructionFiles = projects.flatMap((project) =>
+            glob.sync(`${project}/.github/instructions/*.md`, { cwd }),
+        );
+
+        instructionFiles.forEach((filePath) => {
+            const fileName = path.basename(filePath);
+            createSymlink(
+                path.join(cwd, filePath),
+                path.join(instructionsDir, fileName),
+            );
+        });
+
+        console.log(
+            instructionFiles.length
+                ? `Linked ${instructionFiles.length} instruction file(s) to workspace`
+                : "No AI instruction files found in projects",
+        );
+
+        _.copyAIInstructionsFile("workspace-@", workspaceDir);
+        _.copyAIInstructionsFile("mcp-@", workspaceDir);
+
+        // Open in VS Code
+        try {
+            execSync("code .", { cwd: workspaceDir, stdio: "ignore" });
+            console.log(`\nOpened workspace in VS Code: ${workspaceName}`);
+        } catch {
+            // Silently ignore VS Code errors
+        }
+
+        console.log(`\nWorkspace setup complete: ${workspaceName}`);
+    },
+];

package/globals.js

@@ -215,7 +215,8 @@ if (composer && composer.require && composer.require["laravel/framework"]) {
             args[0] !== "new" &&
             args[0] !== "key" &&
             args[0] !== "dekey" &&
-            args[0] !== "lint"
+            args[0] !== "lint" &&
+            args[0] !== "workspace"
         ) {
             if (!args.find((d) => d === "--force")) {
                 console.log(
@@ -264,7 +265,8 @@ if (composer && composer.require && composer.require["laravel/framework"]) {
             args[0] !== "new" &&
             args[0] !== "key" &&
             args[0] !== "dekey" &&
-            args[0] !== "lint"
+            args[0] !== "lint" &&
+            args[0] !== "workspace"
         ) {
             if (!args.find((d) => d === "--force")) {
                 console.log(
@@ -338,7 +340,8 @@ if (process.env.FW_NEXT) {
         args[0] !== "new" &&
         args[0] !== "key" &&
         args[0] !== "dekey" &&
-        args[0] !== "lint"
+        args[0] !== "lint" &&
+        args[0] !== "workspace"
     ) {
         if (
             !args.find((d) => d === "--force") &&
@@ -570,9 +573,9 @@ if (!existsSync(path.join(cwd, "stylelint.config.js"))) {
     );
 }
 
-function copyAIInstructionsFile(source) {
+function copyAIInstructionsFile(source, projectDir = cwd) {
     // Create directory if it doesn't exist
-    const destDir = path.join(cwd, ".github/instructions");
+    const destDir = path.join(projectDir, ".github/instructions");
     if (!existsSync(destDir)) {
         mkdirSync(destDir, { recursive: true });
     }
@@ -606,11 +609,12 @@ if (
     semver.satisfies(semver.coerce(pkg.dependencies["vue"]), "3.x")
 ) {
     copyAIInstructionsFile("vue-3");
+    copyAIInstructionsFile("ui-framework-3");
 }
 
 if (version) {
-    copyAIInstructionsFile("sass-*");
-    copyAIInstructionsFile("lab-env-*");
+    copyAIInstructionsFile("sass-@");
+    copyAIInstructionsFile("lab-env-@");
     copyAIInstructionsFile("webdriverio-capture-v9");
 }
 
@@ -666,7 +670,8 @@ if (
     args[0] !== "new" &&
     args[0] !== "key" &&
     args[0] !== "dekey" &&
-    args[0] !== "lint"
+    args[0] !== "lint" &&
+    args[0] !== "workspace"
 ) {
     if (!args.find((d) => d === "--force")) {
         // Stop here if diagnosis either unset or outdated
@@ -827,4 +832,5 @@ module.exports = {
             opts,
         );
     },
+    copyAIInstructionsFile,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@fishawack/lab-env",
-    "version": "4.45.0-beta.2",
+    "version": "4.45.0-beta.3",
     "description": "Docker manager for FW",
     "main": "cli.js",
     "scripts": {