@rettangoli/fe 0.0.3

package/README.md

@@ -0,0 +1,324 @@
+
+# Rettangoli Frontend
+
+## Development
+
+Bundle the code under `example` folder using `rettangoli-fe`
+
+```bash
+bun run ../rettangoli-cli/cli.js fe build
+```
+
+Visit the example project that shows the components in action
+
+```bash
+bunx serve ./viz/static
+```
+
+Instead of running `fe build` each time, we can also watch for file changes and bundle the code automatically.
+
+```bash
+bun run ../rettangoli-cli/cli.js fe watch
+```
+
+
+Note: rettangoli-vt is not setup for this project yet. We just use static files under `viz/static` folder.
+
+
+## Introduction
+
+A frontend framework with just 3 type of files to scale from a single page to a full fledged complex application.
+
+Implemented using:
+
+Browser native:
+* web components for components
+
+Runtime:
+* [snabbdom](https://github.com/snabbdom/snabbdom) for virtual dom
+* [immer](https://github.com/immerjs/immer) for data immutability for state management
+* [json-e](https://github.com/json-e/json-e) for templating using json
+* [rxjs](https://github.com/ReactiveX/rxjs) for reactive programming
+
+Build & Development:
+* [esbuild](https://esbuild.github.io/) for bundling
+* [vite](https://vite.dev/) for development
+
+## View Layer
+
+The view layer is unique in that it uses yaml.
+
+* The yaml will be converted into json at build time. The json will then be consumed by snabbdom to be transformed into html through a virtual dom.
+
+### Yaml to write html
+
+Standard html can be totally written in yaml. 
+
+All child element are arrays. Except for things like actual content of text
+
+Use `#` and `.` selectors to represent `id` and `class`.
+
+`div#myid.class1.class2 custorm-attribute=abcd`
+
+will become
+
+`<div id="myid" class="class1 class2" custom-attribute="abcd"></div>`
+
+
+### Templating using json-e
+
+`json-e` templating language allows us to write conditions and loops in our yaml. For example:
+
+
+Loop
+
+```yaml
+template:
+  - rtgl-view w=f g=m:
+    - $map: { $eval: projects }
+      each(v,k):
+        - rtgl-view#project-${v.id} h=64 w=f bw=xs p=m cur=p:
+          - rtgl-text s=lg: "${v.name}"
+          - rtgl-text s=sm: "${v.description}"
+```
+
+Conditional. We usually use `$switch` more as it tends to be more flexible than `$if`.
+
+```yaml
+template:
+  - rtgl-view d=h w=f h=f:
+    - $switch:
+        'showSidebar':
+          - sidebar-component: []
+    - rtgl-view w=f h=f:
+      - $switch:
+          'currentRoute== "/projects"':
+            - projects-component: []
+          'currentRoute== "/profile"':
+```
+
+`json-e` has many more features but we want to keep it simple and in most cases loops and conditionals are enough.
+
+The actual data used in the template is passed in as `viewData` from the state store which we will cover later.
+
+### Define a elementName
+
+```yaml
+elementName: custom-projects
+```
+
+This will be the web component name that will be used for the component.
+
+The component can later be used as `<custom-projects></custom-projects>`.
+
+### Styles
+
+Styles can also be completely written in yaml.
+
+```yaml
+styles:
+  '#title':
+    font-size: 24px
+  '@media (min-width: 768px)':
+    '#title':
+      font-size: 32px
+```
+
+TODO better support nesting and issue with some global selectors.
+
+### Event listeners
+
+```yaml
+refs:
+  createButton:
+    eventListeners:
+      click:
+        handler: handleCreateButtonClick
+  project-*:
+    eventListeners:
+      click:
+        handler: handleProjectsClick
+
+template:
+  - rtgl-button#createButton: Create Project
+  - rtgl-view w=f g=m:
+    - $map: { $eval: projects }
+      each(v,k):
+        - rtgl-view#project-${v.id} h=64 w=f bw=xs p=m cur=p:
+          - rtgl-text s=lg: "${v.name}"
+          - rtgl-text s=sm: "${v.description}"
+```
+
+The above example, will attach event listenrs to `#createButton` and all `#project-*` (wild card support) elements. And bind them to the handlers `handleCreateButtonClick` and `handleProjectsClick`.
+
+### Defining data schema
+
+Component have a few types of data that can be defined using a JSON schema:
+
+* `viewDataSchema` - The data that will used for the template.
+* `propsSchema` - The data that will be passed to the component via javascript, those can be objects.
+* `attrsSchema` - The data that will be passed to the component via html attributes, this is raw strings.
+
+
+```yaml
+viewDataSchema:
+  type: object
+  properties:
+    title:
+      type: string
+      default: Projects
+    createButtonText:
+      type: string
+      default: Create Project
+    projects:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+          name:
+            type: string
+            default: Project 1
+          description:
+            type: string
+            default: Project 1 description
+propsSchema:
+  type: object
+  properties: {}
+```
+
+
+## State Store
+
+* Define `initial state`
+* `toViewData` will take current `state`, `props` and `attrs` and return the `viewData` to be used by the view template
+* Any exported function that starts with `select`  will beceme selectors and are used by handlers to access state data
+* `actions` are all other exported functions that are used to mutate the state.
+
+```js
+export const INITIAL_STATE = Object.freeze({
+  title: "Projects",
+  createButtonText: "Create Project",
+  projects: [
+    {
+      id: "1",
+      name: "Project 1",
+      description: "Project 1 description",
+    },
+    {
+      id: '2',
+      name: 'Project 2',
+      description: 'Project 2 description'
+    }
+  ],
+});
+
+export const toViewData = ({ state, props }, payload) => {
+  return state;
+}
+
+export const selectProjects = (state, props, payload) => {
+  return state.projects;
+}
+
+export const setProjects = (state, payload) => {
+
+}
+```
+
+Note that this is just a dump store, it is not reactive. Components will need to call `deps.render()` from handlers to re-render the component.
+
+## Handlers
+
+`handleOnMount` is a special handler that is called when the component is mounted. It returns a promise that resolves when the component is mounted.
+
+All other exported functions will automatically become handlers and can be used in the view layers's `eventListeners`
+
+A special object called `deps` is injected into all handlers. It has the following properties:
+
+* `deps.render()` will re-render the component. We call this function each time we have chaged state and want to re-render the component.
+* `deps.store` is the store instance. Use selectors to select state and actions to mutate state.
+* `deps.transformedHandlers` can be used to call other handlers.
+* `deps.attrs` is the html attributes that are passed to the component.
+* `deps.props` is the javascript properties that are passed to the component.
+
+
+```js
+export const handleOnMount = (deps) => {
+  () => {
+    // unsubscribe
+  }
+}
+
+export const handleCreateButtonClick = async (e, deps) => {
+  const { store, deps, render } = deps;
+  const formIsVisible = store.selectFormIsVisible();
+
+  if (!formIsVisible) {
+    store.setFormIsVisible(true);
+  }
+  deps.render();
+}
+
+export const handleProjectsClick = (e, deps) => {
+  const id = e.target.id
+  console.log('handleProjectsClick', id);
+}
+```
+
+
+
+* `deps.dispatchEvent` can be used to dispatch custom dom events.
+
+```js
+export const handleProjectsClick = (e, deps) => {
+  deps.dispatchEvent(new CustomEvent('project-clicked', {
+    projectId: '1',
+  }));
+}
+```
+
+
+### Adding additional dependencies
+
+This is a simple yet powerful way to do dependency injection. Those are all global singleton dependencies. Technically anything can be injected and be made accessible to all components.
+
+```js
+const componentDependencies = {
+}
+
+const pageDependencies = {
+}
+
+export const deps = {
+  components: componentDependencies,
+  pages: pageDependencies,
+}
+```
+
+
+## Testing
+
+This framework is written with testability in mind.
+
+
+## View
+
+Visual testing `rettangoli-vt`
+
+
+## State Store
+
+Those are all pure functions and it is straighforward to test them. Actions can be turned into pure functions using immer produce.
+
+Example
+
+```yaml
+...
+```
+
+## Handlers
+
+Test them as normal functions.
+They are not always pure per se due to calling of dependencies. 

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@rettangoli/fe",
+  "version": "0.0.3",
+  "description": "Frontend framework for building reactive web components",
+  "type": "module",
+  "main": "./src/index.js",
+  "keywords": ["frontend", "reactive", "components", "web", "framework"],
+  "files": [
+    "src/*.js",
+    "src/!(cli)",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yuusoft-org/rettangoli.git"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.js",
+    "./cli": "./src/cli/index.js"
+  },
+  "devDependencies": {
+    "js-yaml": "^4.1.0",
+    "esbuild": "^0.25.4",
+    "vite": "^6.3.5"
+  },
+  "dependencies": {
+    "immer": "^10.1.1",
+    "jempl": "^0.0.6",
+    "rxjs": "^7.8.2",
+    "snabbdom": "^3.6.2"
+  },
+  "scripts": {
+    "dev": "node watch.js --watch"
+  }
+}

package/src/common.js

@@ -0,0 +1,203 @@
+import { Subject } from "rxjs";
+
+/**
+ * A custom subject that can be used to dispatch actions and subscribe to them
+ * You can think of this as a bus for all frontend events and communication
+ *
+ * Example:
+ * const subject = new CustomSubject();
+ *
+ * const subscription = subject.subscribe(({ action, payload }) => {
+ *   console.log(action, payload);
+ * });
+ *
+ * subject.dispatch("action", { payload: "payload" });
+ *
+ * subscription.unsubscribe();
+ */
+export class CustomSubject {
+  _subject = new Subject();
+  pipe = (...args) => {
+    return this._subject.pipe(...args);
+  };
+  dispatch = (action, payload) => {
+    this._subject.next({
+      action,
+      payload: payload || {},
+    });
+  };
+  dispatchCall = (action, payload) => {
+    return () => this.dispatch(action, payload || {});
+  };
+}
+
+const getQueryParamsObject = () => {
+  const queryParams = new URLSearchParams(window.location.search + "");
+  const paramsObject = {};
+
+  for (const [key, value] of queryParams.entries()) {
+    paramsObject[key] = value;
+  }
+
+  return paramsObject;
+};
+
+class LayoutOptions {
+  constructor(params) {
+    this._isTouchLayout = params?.isTouchLayout || false;
+  }
+
+  get isTouchLayout() {
+    return this._isTouchLayout;
+  }
+
+  setIsTouchLayout = (isTouchLayout) => {
+    this._isTouchLayout = isTouchLayout;
+  };
+}
+
+const matchPaths = (path, pattern) => {
+  // Normalize paths by removing trailing slashes
+  const normalizedPath = path.endsWith("/") ? path.slice(0, -1) : path;
+  const normalizedPattern = pattern.endsWith("/") ? pattern.slice(0, -1) : pattern;
+
+  // Convert pattern segments with parameters like [id] to regex patterns
+  const regexPattern = normalizedPattern
+    .split("/")
+    .map((segment) => {
+      // Check if segment is a parameter (enclosed in square brackets)
+      if (segment.startsWith("[") && segment.endsWith("]")) {
+        // Extract parameter name and create a capturing group
+        return "([^/]+)";
+      }
+      // Regular segment, match exactly
+      return segment;
+    })
+    .join("/");
+
+  // Create regex with start and end anchors
+  const regex = new RegExp(`^${regexPattern}$`);
+
+  // Test if path matches the pattern
+  return regex.test(normalizedPath);
+};
+
+
+class Request {
+  _authToken;
+
+  constructor(baseUrl, authToken, headers) {
+    this._baseUrl = baseUrl;
+    this._authToken = authToken;
+    this._headers = headers;
+  }
+
+  setAuthToken(token) {
+    this._authToken = token;
+  }
+
+  async request(name, payload, options) {
+    const headers = {
+      "Content-Type": "application/json",
+      ...this._headers,
+    };
+    if (this._authToken) {
+      headers.Authorization = `Bearer ${this._authToken}`;
+    }
+
+    const response = await fetch(`${this._baseUrl}/${name}`, {
+      method: "POST",
+      body: JSON.stringify(payload),
+      headers,
+      credentials: options?.includeCredentials ? "include" : undefined,
+    });
+
+    return response.json();
+  }
+}
+
+/**
+ * @typedef {Object} ApiEndpointConfig
+ * @property {boolean} [includeCredentials] - Whether to include credentials in the request
+ */
+
+/**
+ * Creates an HTTP client with a flexible JSON configuration.
+ * The generated client provides typed methods for each API endpoint based on the configuration.
+ *
+ * @param {Object} config - The client configuration
+ * @param {string} config.baseUrl - Base URL for all API requests
+ * @param {Object} [config.headers={}] - Default headers for all requests
+ * @param {Object.<string, Object.<string, ApiEndpointConfig>>} [config.apis={}] - API configuration object
+ * @returns {Object} The configured HTTP client with API methods
+ */
+export function createHttpClient(config) {
+  const { baseUrl, apis = {}, headers = {} } = config;
+  const requests = new Map();
+
+  const httpClient = {};
+
+  // Create request instances and client structure from configuration
+  Object.entries(apis).forEach(([apiName, endpoints]) => {
+    const apiBaseUrl = `${baseUrl}/${apiName}`;
+    const request = new Request(apiBaseUrl, undefined, headers);
+    requests.set(apiName, request);
+
+    // Create API namespace on the client
+    httpClient[apiName] = {};
+
+    // Create methods for each endpoint
+    Object.entries(endpoints).forEach(([endpointName, options]) => {
+      httpClient[apiName][endpointName] = (body) => {
+        return request.request(endpointName, body, options);
+      };
+    });
+  });
+
+  // Add setAuthToken method to the client
+  httpClient.setAuthToken = (token) => {
+    for (const request of requests.values()) {
+      request.setAuthToken(token);
+    }
+  };
+
+  return httpClient;
+}
+
+
+export const extractCategoryAndComponent = (filePath) => {
+  const parts = filePath.split("/");
+  const component = parts[parts.length - 1].split(".")[0];
+  const category = parts[parts.length - 3];
+  const fileType = parts[parts.length - 1].split(".")[1];
+  return { category, component, fileType };
+}
+
+
+
+// Helper function to flatten arrays while preserving object structure
+export const flattenArrays = (items) => {
+  if (!Array.isArray(items)) {
+    return items;
+  }
+
+  return items.reduce((acc, item) => {
+    if (Array.isArray(item)) {
+      // Recursively flatten nested arrays
+      acc.push(...flattenArrays(item));
+    } else {
+      // If it's an object with nested arrays, process those too
+      if (item && typeof item === "object") {
+        const entries = Object.entries(item);
+        if (entries.length > 0) {
+          const [key, value] = entries[0];
+          if (Array.isArray(value)) {
+            item = { [key]: flattenArrays(value) };
+          }
+        }
+      }
+      acc.push(item);
+    }
+    return acc;
+  }, []);
+};

package/src/commonBuild.js

@@ -0,0 +1,22 @@
+
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+
+// Function to recursively get all files in a directory
+export function getAllFiles(dirPaths, arrayOfFiles = []) {
+  dirPaths.forEach((dirPath) => {
+    const files = readdirSync(dirPath);
+
+    files.forEach((file) => {
+      const fullPath = join(dirPath, file);
+      if (statSync(fullPath).isDirectory()) {
+        arrayOfFiles = getAllFiles([fullPath], arrayOfFiles);
+      } else {
+        arrayOfFiles.push(fullPath);
+      }
+    });
+  });
+
+  return arrayOfFiles;
+}