create-rasti 0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alberto Masuelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,96 @@
+# create-rasti
+
+Scaffold [Rasti](https://rasti.js.org) + [Vite](https://vite.dev) projects from the command line.
+
+Pick a template (SPA, SSR, or pre-rendered Static), add styling, routing, and icon components — get a ready-to-run project in seconds.
+
+## Quick start
+
+```bash
+npm create rasti        # interactive
+npm create rasti my-app # SPA, non-interactive
+```
+
+Create a server-rendered project with routing and Tailwind:
+
+```bash
+npm create rasti my-app --ssr --router --tailwind
+```
+
+## Templates
+
+- **SPA** *(default)*: Rasti + Vite for client-rendered applications.
+- **SSR** *(`--ssr`)*: Rasti + Vite + Express, rendered on the server and hydrated in the browser.
+- **Static** *(`--static`)*: SSR in development, plus `npm run build:static` to pre-render the URLs declared in `static.config.js` into `dist/static`.
+
+For Static projects, string entries derive the output path from the route (`/about/` becomes `about/index.html`). Object entries such as `{ route, output }` allow custom output files, including a top-level `404.html`.
+
+## Styling
+
+Styling options are mutually exclusive:
+
+- **`--tailwind`**: add [Tailwind CSS](https://tailwindcss.com).
+- **`--cssfun`**: add [CSSFUN](https://cssfun.js.org), including light and dark theme setup.
+
+Without either flag, the generated project uses plain CSS.
+
+## Extras
+
+### `--router`
+
+Adds a small universal router built on [path-to-regexp](https://github.com/pillarjs/path-to-regexp). It is copied into the generated project as `src/lib/router.js`, then wired through `src/router-setup.js`, example pages, and an App shell with navigation.
+
+The router is intentionally narrow: route matching, URL creation, browser history, and delegated `a[data-router]` links. It works with SPA, SSR, and Static templates.
+
+### `--icons [preset[,preset...]]`
+
+Generates one Rasti component per SVG icon under `src/icons/`:
+
+```js
+import Heart from './icons/Heart.js';
+// <Heart className="..." width={24} height={24} />
+```
+
+A single preset writes components directly to `src/icons/`. Multiple presets write each set under `src/icons/<preset>/`.
+
+| Preset | Source | License |
+|---|---|---|
+| `heroicons-outline` *(default)* | [Heroicons](https://heroicons.com) by Tailwind Labs | MIT |
+| `heroicons-solid` | [Heroicons](https://heroicons.com) by Tailwind Labs | MIT |
+| `akar-icons` | [Akar Icons](https://akaricons.com) by Arturo Wibawa | MIT |
+| `feathericon` | [Feathericon](https://feathericon.github.io/feathericon/) by Megumi Hano | MIT |
+| `pixelarticons` | [Pixelarticons](https://pixelarticons.com) by Halfmage | MIT |
+
+SVGs are downloaded from GitHub when the project is generated, so this option requires an internet connection.
+
+The CLI writes an `AGENTS.md` to the generated project root with project-specific context (stack, commands, architecture, conventions). It also tries to fetch Rasti's `AGENTS.md` as `AGENTS-RASTI.md`; if that request fails, project generation continues without it.
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--ssr` | Use the SSR template |
+| `--static` | Use the Static template |
+| `--tailwind` | Add Tailwind CSS |
+| `--cssfun` | Add CSSFUN |
+| `--router` | Add micro-router |
+| `--icons [preset[,preset]]` | Add rasti-icons (default preset: `heroicons-outline`) |
+| `--help` | Show help |
+
+`--ssr`/`--static` and `--tailwind`/`--cssfun` are mutually exclusive.
+
+## Development
+
+```bash
+git clone https://github.com/8tentaculos/create-rasti.git
+cd create-rasti
+npm install
+npm run test
+npx create-rasti
+```
+
+Before bumping any version pinned in generated projects, see [`docs/VERSIONS.md`](docs/VERSIONS.md).
+
+## License
+
+[MIT](LICENSE)

package/bin/create-rasti.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+run(process.argv.slice(2));

package/extras/cn/README.md

@@ -0,0 +1,57 @@
+# cn
+
+A tiny helper that joins conditional class names into a single string, for [Rasti](https://rasti.js.org) + Vite projects. It accepts strings, numbers, nested arrays, and objects whose keys are kept when their value is truthy.
+
+## Usage
+
+```javascript
+import cn from './src/index.js';
+
+cn('a', 'b');                     // => 'a b'
+cn('a', { b : true, c : false }); // => 'a b'
+cn('a', ['b', ['c']]);            // => 'a b c'
+cn('base', isActive && 'active'); // conditional, falsy values are skipped
+```
+
+In a Rasti component:
+
+```javascript
+import cn from '../lib/cn.js';
+
+const Button = Component.create`
+    <button class="${({ props }) => cn('button', props.className)}">
+        ${({ props }) => props.renderChildren()}
+    </button>
+`;
+```
+
+## API
+
+`cn(...args)` returns a space-separated `string`.
+
+Each argument may be:
+
+| Type | Behavior |
+|---|---|
+| `string` / `number` | Added as-is when truthy. |
+| `Array` | Flattened recursively (nesting supported). |
+| `Object` | Each key is added when its value is truthy. |
+| falsy (`null`, `undefined`, `false`, `0`, `''`) | Skipped. |
+
+## Copy model
+
+This package is meant to be copied into an application, not installed as a public runtime dependency. `create-rasti` copies `src/index.js` into every generated project as `src/lib/cn.js`.
+
+For manual use:
+
+```bash
+cp extras/cn/src/index.js ./my-project/src/lib/cn.js
+```
+
+```javascript
+import cn from './src/lib/cn.js';
+```
+
+## License
+
+[MIT](../../LICENSE)

package/extras/cn/package.json

@@ -0,0 +1,9 @@
+{
+    "name" : "cn",
+    "version" : "0.0.0",
+    "private" : true,
+    "description" : "Fast conditional class names helper",
+    "type" : "module",
+    "main" : "src/index.js",
+    "license" : "MIT"
+}

package/extras/cn/src/index.js

@@ -0,0 +1,37 @@
+const add = (a, b) => a && b ? a + ' ' + b : '' + (a || b);
+
+const parse = (classes) => {
+    let out = '';
+
+    for (const c of classes) {
+        if (!c) continue;
+
+        const t = typeof c;
+
+        if (t === 'string' || t === 'number') out = add(out, c);
+        else if (Array.isArray(c)) out = add(out, parse(c));
+        else if (t === 'object') for (const key in c) c[key] && (out = add(out, key));
+    }
+
+    return out;
+};
+
+/**
+ * `cn` — fast conditional class names.
+ *
+ * Joins truthy class name arguments into a single space-separated string.
+ * Accepts strings, numbers, arrays (nested supported) and objects whose keys
+ * are included when their value is truthy. Falsy values are skipped.
+ *
+ * @param {...(string|number|Array|Object|null|undefined|boolean)} args - Class name values to join.
+ * @returns {string} The merged class name string.
+ *
+ * @example
+ * cn('a', 'b'); // => 'a b'
+ * cn('a', { b : true, c : false }); // => 'a b'
+ * cn('a', ['b', ['c']]); // => 'a b c'
+ * cn('a', isActive && 'active'); // conditional
+ */
+const cn = (...args) => parse(args);
+
+export default cn;

package/extras/micro-router/README.md

@@ -0,0 +1,78 @@
+# micro-router
+
+A minimal router for [Rasti](https://rasti.js.org) + Vite projects. It handles route matching, URL creation, browser history, and delegated link clicks. Matching is powered by [path-to-regexp](https://github.com/pillarjs/path-to-regexp).
+
+## Why it exists
+
+[Rasti](https://rasti.js.org) projects need routing that runs the same way in the browser and during SSR. This router stays small for that use case: no framework adapters, no component API, and no rendering opinion. It was written for `create-rasti`, but it only depends on plain JavaScript route objects and actions.
+
+## Usage
+
+```javascript
+import createRouter from './src/index.js';
+
+const routes = [
+    { path : '/', action : (location) => { /* render Home */ } },
+    { path : '/about', action : (location) => { /* render About */ } },
+    { path : '/users/:id', action : (location) => { /* render User, location.params.id */ } }
+];
+
+const router = createRouter(routes, { baseUrl : '' });
+
+// Browser: delegate link clicks and bind history.
+router.delegateNavigation(document.querySelector('#app'));
+router.bindHistory();
+
+// Programmatic navigation.
+router.navigate('/about');
+
+// Async actions can be awaited.
+await router.navigate('/users/123');
+
+// URL building with params and query.
+router.createUrl('/users/:id', { id : '123' }, { tab : 'posts' });
+// => '/users/123?tab=posts'
+```
+
+In the browser, links opt in to client-side navigation with `data-router`:
+
+```html
+<a href="/about" data-router>About</a>
+```
+
+## API
+
+`createRouter(routes, options?)` returns `{ navigate, createUrl, delegateNavigation, bindHistory }`.
+
+| Method | Description |
+|---|---|
+| `navigate(url, options?)` | Matches `url`, updates browser history when available, invokes the matched route's `action(location)`, and returns the action result. Async actions return a Promise. Options: `{ addToHistory = true, replaceHistory = false }`. |
+| `createUrl(path, params?, query?)` | Builds a URL from a route path, route params, and query params. |
+| `delegateNavigation(rootElement)` | Intercepts left-clicks on descendant `a[data-router]` links and routes them through `navigate`. Returns a cleanup function. |
+| `bindHistory()` | Listens for `popstate` and navigates to the current URL without pushing a new history entry. Returns a cleanup function. |
+
+**Options:** `{ baseUrl?: string }` — prepended to generated URLs and stripped before matching.
+
+**Route:** `{ path: string, action: (location) => any }`.
+
+**Location:** `{ path, params, query, test(url): boolean }` — `params` and `query` are plain objects; `test(url)` reports whether a URL matches the same route.
+
+Full type signatures live in the JSDoc of `src/index.js`.
+
+## Copy model
+
+This package is meant to be copied into an application, not installed as a public runtime dependency. `create-rasti --router` copies `src/index.js` into the generated project as `src/lib/router.js` and adds `path-to-regexp` to that project's dependencies.
+
+For manual use:
+
+```bash
+cp -r extras/micro-router/src ./my-project/src/router
+```
+
+```javascript
+import createRouter from './src/router/index.js';
+```
+
+## License
+
+[MIT](../../LICENSE)

package/extras/micro-router/package-lock.json

@@ -0,0 +1,26 @@
+{
+    "name": "micro-router",
+    "version": "0.0.0",
+    "lockfileVersion": 3,
+    "requires": true,
+    "packages": {
+        "": {
+            "name": "micro-router",
+            "version": "0.0.0",
+            "license": "MIT",
+            "dependencies": {
+                "path-to-regexp": "^8.0.0"
+            }
+        },
+        "node_modules/path-to-regexp": {
+            "version": "8.3.0",
+            "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.3.0.tgz",
+            "integrity": "sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA==",
+            "license": "MIT",
+            "funding": {
+                "type": "opencollective",
+                "url": "https://opencollective.com/express"
+            }
+        }
+    }
+}

package/extras/micro-router/package.json

@@ -0,0 +1,12 @@
+{
+    "name" : "micro-router",
+    "version" : "0.0.0",
+    "private" : true,
+    "description" : "Minimal universal router",
+    "type" : "module",
+    "main" : "src/index.js",
+    "dependencies" : {
+        "path-to-regexp" : "^8.0.0"
+    },
+    "license" : "MIT"
+}

package/extras/micro-router/src/index.js

@@ -0,0 +1,192 @@
+import { match, compile } from 'path-to-regexp';
+
+/**
+ * @typedef {Object} Location
+ * @property {string} path - The route path pattern (e.g., `/user/:id`).
+ * @property {Object.<string, string>} params - The route parameters extracted from the URL path, sanitized to prevent injection attacks.
+ * @property {Object.<string, string>} query - The query parameters parsed from the URL query string.
+ * @property {function(string): boolean} test - A function to test if a given URL matches this route. Returns `true` if the URL matches the route, `false` otherwise.
+ */
+
+/**
+ * @typedef {Object} Route
+ * @property {string} path - The route path pattern (e.g., `/user/:id`).
+ * @property {function(Location): *} action - The action function to call when the route matches. Receives a `Location` object as parameter.
+ */
+
+/**
+ * @typedef {Object} Router
+ * @property {function(string, Object=): *} navigate - Navigates to a given URL, matches a route, and returns its action result.
+ * @property {function(string, Object=, Object=): string} createUrl - Creates a URL from a route path, parameters, and query string.
+ * @property {function(HTMLElement): function(): void} delegateNavigation - Delegates navigation events for links with `data-router` attributes. Returns a cleanup function.
+ * @property {function(): function(): void} bindHistory - Binds browser history changes to the navigation logic. Returns a cleanup function.
+ */
+
+/**
+ * Creates a router with navigation, URL creation, and event delegation.
+ * @param {Array.<Route>} routes - Array of route objects. Each route must have a `path` and an `action` function.
+ * @param {Object} [routerOptions={}] - Options for the router.
+ * @param {string} [routerOptions.baseUrl=''] - A base URL to prepend to all routes and navigation.
+ * @returns {Router} - Router object with navigation, URL creation, and event delegation methods.
+ */
+export default function createRouter(routes, routerOptions = {}) {
+    const { baseUrl = '' } = routerOptions;
+
+    /**
+     * Gets the pathname and query string from a given url.
+     * @param {string} url - The url to get the pathname and query string from.
+     * @returns {Object} - The pathname and query string.
+     * @private
+     */
+    const getUrlParts = (url) => {
+        const [pathname, query] = url.replace(baseUrl, '').split('?');
+        return { pathname, query };
+    };
+
+    /**
+     * Gets the match result from a given pathname and route path.
+     * @param {string} pathname - The pathname to match.
+     * @param {string} routePath - The route path to match.
+     * @returns {Object|null} - The match result, or `null` if no match is found.
+     * @private
+     */
+    const getMatch = (pathname, routePath) => {
+        const matcher = match(routePath, { decode : decodeURIComponent });
+        return matcher(pathname);
+    };
+
+    /**
+     * Matches a given url against the routes.
+     * @param {string} url - The url to match.
+     * @returns {(function(): *)|null} - A function that calls the matched route's action with a `Location` object, or `null` if no match is found.
+     * @private
+     */
+    const matchRoute = (url) => {
+        const { pathname, query } = getUrlParts(url);
+
+        for (const route of routes) {
+            const matched = getMatch(pathname, route.path);
+
+            if (matched) {
+                /** @type {Location} */
+                const location = {
+                    path : route.path,
+                    params : sanitizeParams(matched.params),
+                    query : Object.fromEntries(new URLSearchParams(query).entries()),
+                    test : (url) => !!getMatch(getUrlParts(url).pathname, route.path)
+                };
+
+                return () => route.action(location);
+            }
+        }
+
+        return null;
+    };
+
+    /**
+     * Navigates to a given path, matches a route, and calls its action with a `Location` object.
+     * @param {string} url - The path to navigate to, including query string.
+     * @param {Object} [options={}] - Options for navigation.
+     * @param {boolean} [options.addToHistory=true] - Whether to add the navigation to the browser's history.
+     * @param {boolean} [options.replaceHistory=false] - Whether to replace the current history entry instead of adding a new one.
+     * @returns {*} The matched route action result, or `undefined` if no route matches. Async actions return a Promise.
+     */
+    const navigate = (url, options = {}) => {
+        const { addToHistory = true, replaceHistory = false } = options;
+        // Match the route and query
+        const matched = matchRoute(url);
+
+        if (matched) {
+            // Handle browser history
+            if (addToHistory && typeof window !== 'undefined') {
+                window.history[replaceHistory ? 'replaceState' : 'pushState']({}, '', url);
+            }
+            // Call the route's action
+            return matched();
+        } else {
+            console.error('No route matched:', url);
+        }
+
+        return undefined;
+    };
+
+    /**
+     * Creates a URL from a route path, parameters, and query string.
+     * @param {string} path - The route path (e.g., `/user/:id`).
+     * @param {Object.<string, string>} [params={}] - Parameters to replace in the path (e.g., `{ id : '123' }` for `/user/:id`).
+     * @param {Object.<string, string>} [query={}] - Query parameters to append to the URL (e.g., `{ page : '1', sort : 'name' }`).
+     * @returns {string} - The generated URL with query parameters.
+     */
+    const createUrl = (path, params = {}, query = {}) => {
+        const toPath = compile(path, { encode : encodeURIComponent });
+        const basePath = toPath(params);
+
+        const queryString = new URLSearchParams(query).toString();
+        return `${baseUrl}${queryString ? `${basePath}?${queryString}` : basePath}`;
+    };
+
+    /**
+     * Delegates navigation events for links with `data-router` attributes.
+     * @param {HTMLElement} rootElement - The root element to listen for click events.
+     * @returns {Function} - A function to undelegate the event listener.
+     */
+    const delegateNavigation = (rootElement) => {
+        const handleClick = (event) => {
+            if (
+                event.defaultPrevented ||
+                event.button !== 0 || // Only left-click
+                event.metaKey || event.ctrlKey || event.shiftKey || event.altKey // Modifier keys
+            ) {
+                return;
+            }
+
+            const anchor = event.target.closest('a[data-router]');
+
+            if (anchor && anchor.href) {
+                event.preventDefault();
+                const url = new URL(anchor.href);
+                window.scrollTo({ top : 0, behavior : 'instant' });
+                navigate(url.pathname + url.search);
+            }
+        };
+        // Bind the click event to the root element.
+        rootElement.addEventListener('click', handleClick);
+        // Return a function to remove the event listener.
+        return () => {
+            rootElement.removeEventListener('click', handleClick);
+        };
+    };
+
+    /**
+     * Binds browser history changes to the navigation logic.
+     * @returns {Function} - A function to unbind the `popstate` event listener.
+     */
+    const bindHistory = () => {
+        const handlePopState = () => {
+            // On popstate, navigate to the current URL
+            navigate(window.location.pathname + window.location.search, { addToHistory : false });
+        };
+
+        window.addEventListener('popstate', handlePopState);
+
+        // Return a function to remove the event listener
+        return () => {
+            window.removeEventListener('popstate', handlePopState);
+        };
+    };
+
+    /**
+     * Sanitizes route parameters to prevent injection attacks.
+     * @param {Object} params - The route parameters.
+     * @returns {Object} - The sanitized parameters.
+     */
+    const sanitizeParams = (params) => {
+        const sanitized = {};
+        for (const [key, value] of Object.entries(params)) {
+            sanitized[key] = String(value).replace(/[<>]/g, '');
+        }
+        return sanitized;
+    };
+
+    return { navigate, createUrl, delegateNavigation, bindHistory };
+}

package/extras/rasti-icons/README.md

@@ -0,0 +1,65 @@
+# rasti-icons
+
+Generate [Rasti](https://rasti.js.org) components from GitHub-hosted SVG icon sets.
+
+This tool is used by `create-rasti --icons`, and it can also run directly when a project needs to regenerate icons or use a custom SVG source.
+
+## With create-rasti
+
+```bash
+npm create rasti my-app --icons
+npm create rasti my-app --icons pixelarticons
+npm create rasti my-app --icons heroicons-outline,heroicons-solid
+```
+
+The default preset is `heroicons-outline`. A single preset writes components to `src/icons/`; multiple presets write each set to `src/icons/<preset>/`.
+
+## Standalone usage
+
+### Built-in presets
+
+```bash
+node bin/rasti-icons.js --preset heroicons-outline
+node bin/rasti-icons.js --preset akar-icons --output ./src/icons
+node bin/rasti-icons.js --preset feathericon --output ./src/icons
+node bin/rasti-icons.js --preset pixelarticons --output ./src/icons
+```
+
+Available presets: `heroicons-outline`, `heroicons-solid`, `akar-icons`, `feathericon`, `pixelarticons`.
+
+When `--output` is omitted, preset output defaults to `./icons/<preset>`.
+
+### Custom SVG set
+
+```bash
+node bin/rasti-icons.js \
+  --source https://api.github.com/repos/owner/repo/contents/path/to/svgs \
+  --license https://raw.githubusercontent.com/owner/repo/main/LICENSE \
+  --output ./icons
+```
+
+`--source` must be a GitHub API directory listing URL that returns a JSON array of file objects with `download_url`. `--license` is optional. Custom source output defaults to `./icons`.
+
+## Generated components
+
+Each SVG file becomes a Rasti component. The generated component accepts optional `props.className`, `props.width`, and `props.height`. If width or height is not provided, the original SVG dimensions are used.
+
+```javascript
+import Heart from './icons/Heart.js';
+
+// Mount with default size.
+Heart.mount({}, container);
+
+// Mount with custom class and size.
+Heart.mount({ className : 'icon icon-red', width : '32', height : '32' }, container);
+```
+
+Icon filenames are converted from `kebab-case.svg` to `PascalCase.js`.
+
+## Licenses
+
+Each generated output directory contains a `LICENSE.txt` with the upstream icon set license when a license URL is provided.
+
+## License
+
+[MIT](../../LICENSE)