@papit/create 0.0.1

package/README.md

@@ -0,0 +1,198 @@
+# @papit/create
+
+Project and package scaffolding tool for @papit — opinionated, consistent, and designed to kickstart Papit-based projects with the correct structure from day one.
+
+![Logo](https://raw.githubusercontent.com/onkelhoy/papit/refs/heads/main/asset/logo.svg)
+
+This package is intended to be used **from within a workspace or an empty directory**. Simply run:
+
+```bash
+npm create @papit
+```
+
+to generate a fully initialized Papit package, component, or project with zero or minimal configuration.
+
+---
+
+![Type](https://img.shields.io/badge/Type-cli-orange)
+[![Tests](https://github.com/onkelhoy/papit/actions/workflows/pull-request.yml/badge.svg)](https://github.com/onkelhoy/papit/actions/workflows/pull-request.yml)
+[![NPM version](https://img.shields.io/npm/v/@papit/create.svg?logo=npm)](https://www.npmjs.com/package/@papit/create)
+
+---
+
+## CLI Flags
+
+| Flag          | Description                         |
+| ------------- | ----------------------------------- |
+| `--package`   | Create a package                    |
+| `--component` | Create a component                  |
+| `--project`   | Create a project                    |
+| `--agree`     | Skip confirmations                  |
+| `--install`   | Install dependencies after creation |
+| `--commit`    | Create an initial git commit        |
+| `--verbose`   | Show detailed output                |
+
+If no creation flag is provided, an interactive selector is shown.
+
+---
+
+## How it works
+
+`@papit/create` presents a set of creation options. Some of these can be invoked directly via flags, but the tool is primarily interactive and focused on generating boilerplate code based on predefined templates.
+
+There are currently three built-in runners:
+
+1. `package`
+2. `component`
+3. `project`
+
+**Note:** You can provide your own custom runners by placing them in the `bin` folder. Each runner must have a `runner.js` file with a default export, for example:
+
+```
+<workspace-root>/bin/runners/<custom>/runner.js
+```
+
+A runner is a function that receives two arguments:
+
+```ts
+info: {
+  root: string; // Location of the workspace root
+  local: string; // Location of the current package (if any)
+  script: string | null; // Location of the @papit/create script
+}
+```
+
+```ts
+args: {
+  flags: Record<string, string | string[] | true | undefined>,
+  values: string[]
+}
+```
+
+For more details on the structure and behavior of these arguments, see the
+
+- `@papit/arguments`
+- `@papit/information`
+  package.
+
+---
+
+## Package
+
+The **package runner** creates a new package at a selected location (sometimes referred to as layers or folders).
+
+A template is selected — either one of the built-in templates or a custom template located at:
+
+```
+<workspace-root>/bin/runners/package/*
+```
+
+The selected template folder is copied, and all files are processed to replace supported variables.
+
+The generated license file automatically references the same license as the workspace root.
+
+### Available variables
+
+- `VARIABLE_NAME`
+- `VARIABLE_FULL_NAME`
+- `VARIABLE_DESCRIPTION`
+- `VARIABLE_LAYER_FOLDER`
+- `VARIABLE_PROJECTLICENSE`
+- `VARIABLE_GITHUB_REPO`
+- `VARIABLE_LOCAL_DESTINATION`
+- `VARIABLE_CLASS_NAME`
+- `VARIABLE_HTML_PREFIX`
+- `VARIABLE_USER`
+
+---
+
+## Component
+
+The **component runner** creates a new component and is intended for adding sub-components to an existing package.
+
+Like the package runner, it copies a selected template from either built-ins or:
+
+```
+<workspace-root>/bin/runners/component/*
+```
+
+### Folder handling
+
+- **views**
+  If a `views` folder exists in both the current package and the template, a new subfolder named after the component is created inside the package’s `views` directory and populated with the template content.
+
+- **src**
+  If the current package already has a `src` folder with files, the template’s `src` content is typically placed under:
+
+  ```
+  src/components/<component-name>
+  ```
+
+### Available variables
+
+- `VARIABLE_NAME`
+- `VARIABLE_FULL_NAME`
+- `VARIABLE_HTML_NAME`
+- `VARIABLE_CLASS_NAME`
+
+---
+
+## Project
+
+> ⚠️ This runner is currently under development.
+
+The **project runner** creates a raw monorepo project at a selected destination.
+
+As with packages and components, custom templates can be provided at:
+
+```
+<workspace-root>/bin/runners/project/*
+```
+
+You will be prompted to select a template during creation.
+
+Licensing is handled interactively. You may provide an existing license file or omit it, in which case a standard MIT license is used.
+
+### Available variables
+
+- `VARIABLE_NAME`
+- `VARIABLE_DESCRIPTION`
+- `VARIABLE_PROJECTLICENSE`
+- `VARIABLE_USER`
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+Please ensure that:
+
+- Templates follow Papit conventions
+- Runners remain deterministic
+- Interactive prompts stay minimal
+
+Open a pull request when ready 🚀
+
+---
+
+## License
+
+Licensed under the **@Papit License 1.0**
+Copyright (c) 2024 Henry Pap (@onkelhoy)
+
+**Key points:**
+
+- ✅ Free to use in commercial projects
+- ✅ Free to modify and distribute
+- ✅ Attribution required
+- ❌ Cannot resell the component itself as a standalone product
+
+See the [LICENSE](https://github.com/onkelhoy/papit/blob/main/LICENSE) file for full details.
+
+---
+
+## Support
+
+For issues, questions, or contributions, please visit the
+[GitHub repository](https://github.com/onkelhoy/papit).

package/asset/component-templates/browser/src/component.ts

@@ -0,0 +1,7 @@
+// import statements 
+
+export class VARIABLE_CLASS_NAME {
+  constructor() {
+
+  }
+}

package/asset/component-templates/browser/src/index.ts

@@ -0,0 +1,3 @@
+// exports
+export * from "./component";
+export * from "./types";

package/asset/component-templates/browser/src/types.ts

@@ -0,0 +1 @@
+export { }

package/asset/component-templates/browser/tests/index.html

@@ -0,0 +1,15 @@
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>VARIABLE_NAME test</title>
+
+    <script type="module" defer src="main.js"></script>
+</head>
+
+<body>
+    <h1>VARIABLE_NAME test</h1>
+</body>
+
+</html>

package/asset/component-templates/browser/tests/main.js

@@ -0,0 +1 @@
+import 'VARIABLE_FULL_NAME';

package/asset/component-templates/browser/tests/public/translations/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "region": "GB",
+    "language": "en-UK"
+  },
+  "VARIABLE_NAME": "VARIABLE_NAME"
+}

package/asset/component-templates/browser/tests/snapshot.test.ts

@@ -0,0 +1,12 @@
+import { test, expect } from '@playwright/test';
+
+test.beforeEach(async ({ page }) => {
+  // Navigate to your test page
+  await page.goto('tests/VARIABLE_NAME/');
+});
+
+test.describe("VARIABLE_FULL_NAME visual regression", () => {
+  test('default snapshot', async ({ page }) => {
+    await expect(page).toHaveScreenshot();
+  });
+})

package/asset/component-templates/browser/tests/unit.test.ts

@@ -0,0 +1,69 @@
+import { test, expect } from '@playwright/test';
+
+test.beforeEach(async ({ page }) => {
+  // Navigate to your test page
+  await page.goto('tests/VARIABLE_NAME/');
+});
+
+declare global {
+  interface Window {
+    EVENT_EMITTED: any;
+  }
+}
+
+test.describe("VARIABLE_FULL_NAME unit tests", () => {
+  test('available in DOM', async ({ page }) => {
+    // Interact with your component and make assertions
+    const component = await page.$('VARIABLE_HTML_NAME');
+    expect(component).not.toBeNull();
+  });
+});
+
+test.describe.skip("helpers", () => {
+  test("wait for event : enter press", async ({ page }) => {
+    const target = page.getByTestId("base-target");
+    await page.evaluate(() => {
+      window.EVENT_EMITTED = null;
+      const target = document.querySelector<HTMLElement>("*[data-testid='base-target']");
+      if (!target) return;
+
+      target.addEventListener("event-name", () => {
+        window.EVENT_EMITTED = true;
+      });
+
+      target.focus();
+      target.dispatchEvent(new KeyboardEvent("up", { key: "Enter" }));
+      // enter is tricky to capture so we make sure to dispatch inside evalute
+    });
+
+    await target.focus();
+    await target.press("Enter");
+
+    expect(await page.evaluate(() => window.EVENT_EMITTED)).toBeTruthy();
+  });
+
+  test("should submit a form", async ({ page }) => {
+    // NOTE this requires in main.js you have form.onsubmit = (e) => { e.preventDefault() }
+    // setting this in evaluate did not work.. (maybe with page.evalute)
+
+    await page.getByTestId("a").fill("hello");
+    await page.getByTestId("submit").click();
+
+    const results = await page.evaluate(() => {
+      const form = document.querySelector("form");
+      if (!form) return null;
+
+      const formdata = new FormData(form);
+      return {
+        a: formdata.get("a"),
+        b: formdata.get("b"),
+      }
+    });
+
+    expect(results).not.toBe(null);
+    expect(results).toMatchObject({
+      a: "hello",
+      b: "value",
+    });
+  });
+});

package/asset/component-templates/browser/views/index.html

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>VARIABLE_CLASS_NAME | experiment</title>
+
+    <link rel="icon" type="image/x-icon" href="favicon.ico">
+
+    <!-- Styles -->
+    <link rel="stylesheet" href="style.css" />
+
+    <script defer type="module" src="main.js"></script>
+</head>
+
+<body>
+
+    <h1>VARIABLE_CLASS_NAME | experiment</h1>
+    <section>
+        <h2>Example</h2>
+        <pap-codeblock>
+            <VARIABLE_HTML_NAME></VARIABLE_HTML_NAME>
+        </pap-codeblock>
+    </section>
+</body>
+
+</html>

package/asset/component-templates/browser/views/main.js

@@ -0,0 +1,13 @@
+import { translator } from '@papit/translator';
+import "@papit/codeblock";
+
+// component
+import 'VARIABLE_FULL_NAME';
+
+window.onload = () => {
+    console.log('[demo]: window loaded');
+
+    translator.add({ id: "en", url: "/en.json" });
+    translator.change("en");
+}
+

package/asset/component-templates/browser/views/public/translations/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "region": "GB",
+    "language": "en-UK"
+  },
+  "VARIABLE_NAME": "VARIABLE_NAME"
+}

package/asset/component-templates/browser/views/style.css

@@ -0,0 +1,28 @@
+@import "@papit/theme";
+
+body {
+    background-color: var(--background, light-dark(oklch(96% 0 0), oklch(17% 0 0)));
+    color: var(--text, light-dark(oklch(10% 0 0), oklch(95% 0 0)));
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-4, 16px);
+
+    padding-block: 5rem;
+
+    h1 {
+        max-width: 1200px;
+        margin-inline: auto;
+        width: 100%;
+    }
+
+    section {
+        max-width: 1200px;
+        margin-inline: auto;
+        width: 100%;
+        box-sizing: border-box;
+        padding: 1rem 2rem;
+        border-radius: 1rem;
+        border: 1px solid light-dark(oklch(88% 0.01 264), oklch(28% 0.015 264));
+        background-color: var(--background-light, light-dark(oklch(99% 0 0), oklch(22% 0 0)));
+    }
+}

package/asset/component-templates/game/src/component.ts

@@ -0,0 +1,7 @@
+// import statements 
+
+export class VARIABLE_CLASS_NAME {
+  constructor() {
+
+  }
+}

package/asset/component-templates/game/src/index.ts

@@ -0,0 +1,3 @@
+// exports
+export * from "./component";
+export * from "./types";

package/asset/component-templates/game/src/types.ts

@@ -0,0 +1 @@
+export {}

package/asset/component-templates/game/tests/index.html

@@ -0,0 +1,15 @@
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>PLACEHOLDER_NAME test</title>
+
+    <script type="module" defer src="main.js"></script>
+</head>
+
+<body>
+    <canvas>Your browser does not support HTML canvas</canvas>
+</body>
+
+</html>

package/asset/component-templates/game/tests/main.js

@@ -0,0 +1,34 @@
+// core
+import { Engine } from '@papit/game-engine';
+import { InputEvents } from "@papit/game-input-events";
+
+// component
+import 'VARIABLE_FULL_NAME';
+
+let engine, events;
+
+window.onload = () => {
+  engine = new Engine("canvas");
+  events = new InputEvents(engine.canvas, { mouse: { pointerlock: false } });
+
+  events.on("mouse-up", handlemouseup);
+  events.on("mouse-down", handlemousedown);
+  events.on("mouse-move", handlemousemove);
+
+  engine.loop(draw); // cool function
+}
+
+function draw() {
+  engine.ctx.clearRect(0, 0, engine.width, engine.height);
+}
+
+// event handlers
+function handlemousemove(e) {
+  // mouse move
+}
+function handlemousedown(e) {
+  // mouse down 
+}
+function handlemouseup(e) {
+  // mouse up 
+}

package/asset/component-templates/game/tests/public/translations/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "region": "GB",
+    "language": "en-UK"
+  },
+  "VARIABLE_NAME": "VARIABLE_NAME"
+}

package/asset/component-templates/game/tests/snapshot.test.ts

@@ -0,0 +1,12 @@
+import { test, expect } from '@playwright/test';
+
+test.beforeEach(async ({ page }) => {
+  // Navigate to your test page
+  await page.goto('tests/VARIABLE_NAME/');
+});
+
+test.describe("VARIABLE_FULL_NAME visual regression", () => {
+  test('default snapshot', async ({ page }) => {
+    await expect(page).toHaveScreenshot();
+  });
+})

package/asset/component-templates/game/tests/unit.test.ts

@@ -0,0 +1,18 @@
+import { test, expect } from '@playwright/test';
+
+test.beforeEach(async ({ page }) => {
+  // Navigate to your test page
+  await page.goto('tests/VARIABLE_NAME/');
+});
+
+declare global {
+  interface Window {
+    EVENT_EMITTED: any;
+  }
+}
+
+test.describe.skip("VARIABLE_FULL_NAME unit tests", () => {
+  test('available in DOM', async ({ page }) => {
+    // honestly dont know what to test 
+  });
+});

package/asset/component-templates/game/views/index.html

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>VARIABLE_CLASS_NAME | experiment</title>
+
+    <link rel="icon" type="image/x-icon" href="favicon.ico">
+
+    <!-- Styles -->
+    <link rel="stylesheet" href="style.css" />
+
+    <script type="module" defer src="main.js"></script>
+</head>
+
+<body>
+    <canvas>Your browser does not support HTML canvas</canvas>
+</body>
+
+</html>

package/asset/component-templates/game/views/main.js

@@ -0,0 +1,34 @@
+// core
+import { Engine } from '@papit/game-engine';
+import { InputEvents } from "@papit/game-input-events";
+
+// component
+import 'VARIABLE_FULL_NAME';
+
+let engine, events;
+
+window.onload = () => {
+  engine = new Engine("canvas");
+  events = new InputEvents(engine.canvas, { mouse: { pointerlock: false } });
+
+  events.on("mouse-up", handlemouseup);
+  events.on("mouse-down", handlemousedown);
+  events.on("mouse-move", handlemousemove);
+
+  engine.loop(draw); // cool function
+}
+
+function draw() {
+  engine.ctx.clearRect(0, 0, engine.width, engine.height);
+}
+
+// event handlers
+function handlemousemove(e) {
+  // mouse move
+}
+function handlemousedown(e) {
+  // mouse down 
+}
+function handlemouseup(e) {
+  // mouse up 
+}

package/asset/component-templates/game/views/public/translations/en.json

@@ -0,0 +1,7 @@
+{
+  "meta": {
+    "region": "GB",
+    "language": "en-UK"
+  },
+  "VARIABLE_NAME": "VARIABLE_NAME"
+}

package/asset/component-templates/game/views/style.css

@@ -0,0 +1,9 @@
+@import "@papit/theme";
+
+body {
+    background-color: var(--background, light-dark(oklch(96% 0 0), oklch(17% 0 0)));
+    color: var(--text, #080808);
+    margin: 0;
+    background-image: radial-gradient(circle at 50% 50%, var(--background-darkest) 1px, transparent 0);
+    background-size: 20px 20px;
+}

package/asset/component-templates/node/src/component.ts

@@ -0,0 +1,7 @@
+// import statements 
+
+export class VARIABLE_CLASS_NAME {
+  constructor() {
+
+  }
+}

package/asset/component-templates/node/src/index.ts

@@ -0,0 +1,3 @@
+// exports
+export * from "./component";
+export * from "./types";

package/asset/component-templates/node/src/types.ts

@@ -0,0 +1 @@
+export {}

package/asset/component-templates/node/tests/unit.test.js

@@ -0,0 +1,10 @@
+import { describe, it, beforeEach } from "node:test";
+import assert from "node:assert";
+
+describe('A thing', () => {
+  beforeEach(() => console.log('about to run a test'));
+
+  it('should work', () => {
+    assert.strictEqual(1, 1);
+  });
+});