toiljs 0.0.4 → 0.0.6

package/src/cli/index.ts

@@ -6,7 +6,9 @@
  */
 import { build, dev, start } from 'toiljs/compiler';
 
+import { runConfigure } from './configure.js';
 import { runCreate, type Template } from './create.js';
+import { PREPROCESSORS, type Preprocessor } from './features.js';
 import { accent, banner, bold, danger, dim, success, version } from './ui.js';
 
 interface Flags {
@@ -14,6 +16,9 @@ interface Flags {
     port?: number;
     name?: string;
     template?: Template;
+    preprocessor?: Preprocessor;
+    tailwind?: boolean;
+    ai?: boolean;
     install?: boolean;
     git?: boolean;
     pm?: string;
@@ -28,9 +33,11 @@ function parseArgs(argv: string[]): Flags {
             case '--root':
                 flags.root = argv[++i];
                 break;
-            case '--port':
-                flags.port = Number(argv[++i]);
+            case '--port': {
+                const port = Number(argv[++i]);
+                if (!Number.isNaN(port)) flags.port = port;
                 break;
+            }
             case '--template':
             case '-t': {
                 const t = argv[++i];
@@ -40,6 +47,23 @@ function parseArgs(argv: string[]): Flags {
             case '--pm':
                 flags.pm = argv[++i];
                 break;
+            case '--style': {
+                const s = argv[++i];
+                if ((PREPROCESSORS as readonly string[]).includes(s)) flags.preprocessor = s as Preprocessor;
+                break;
+            }
+            case '--tailwind':
+                flags.tailwind = true;
+                break;
+            case '--no-tailwind':
+                flags.tailwind = false;
+                break;
+            case '--ai':
+                flags.ai = true;
+                break;
+            case '--no-ai':
+                flags.ai = false;
+                break;
             case '--install':
                 flags.install = true;
                 break;
@@ -57,7 +81,6 @@ function parseArgs(argv: string[]): Flags {
                 flags.yes = true;
                 break;
             default:
-                // First bare (non-flag) token is the positional project name.
                 if (!arg.startsWith('-') && flags.name === undefined) flags.name = arg;
         }
     }
@@ -72,6 +95,7 @@ function printHelp(): void {
             '',
             bold('Commands'),
             cmd('create [name]', 'scaffold a new toiljs app'),
+            cmd('configure', 'toggle styling features (Sass/Less/Stylus, Tailwind)'),
             cmd('dev', 'start the dev server with HMR'),
             cmd('build', 'build the optimized production bundle'),
             cmd('start', 'self-host the built app (hyper-express / uWS)'),
@@ -80,6 +104,9 @@ function printHelp(): void {
             cmd('--root <dir>', 'project root (default: current directory)'),
             cmd('--port <n>', 'dev server port'),
             cmd('-t, --template', 'create: app | minimal'),
+            cmd('--style <name>', 'create/configure: css | sass | less | stylus'),
+            cmd('--tailwind', 'create/configure: enable Tailwind (--no-tailwind to remove)'),
+            cmd('--no-ai', 'create: skip AI assistant files (CLAUDE.md, etc.)'),
             cmd('-y, --yes', 'create: accept defaults (non-interactive)'),
             cmd('--no-install', "create: don't install dependencies"),
             cmd('-v, --version', 'print the toiljs version'),
@@ -104,6 +131,9 @@ async function main(): Promise<void> {
             await runCreate({
                 name: flags.name,
                 template: flags.template,
+                preprocessor: flags.preprocessor,
+                tailwind: flags.tailwind,
+                ai: flags.ai,
                 install: flags.install,
                 git: flags.git,
                 pm: flags.pm,
@@ -112,6 +142,17 @@ async function main(): Promise<void> {
             });
             break;
 
+        case 'configure':
+            banner();
+            await runConfigure({
+                root: flags.root,
+                preprocessor: flags.preprocessor,
+                tailwind: flags.tailwind,
+                install: flags.install,
+                cwd: process.cwd(),
+            });
+            break;
+
         case 'dev':
             banner();
             process.stdout.write(dim('  starting dev server…') + '\n\n');

package/src/cli/proc.ts

@@ -0,0 +1,20 @@
+import { spawn } from 'node:child_process';
+
+/**
+ * Spawns `cmd args` in `cwd`, resolving on a 0 exit code and rejecting otherwise. On Windows the
+ * `npm`/`pnpm`/`yarn` shims are `.cmd` files that need a shell; passing an args array with
+ * `shell: true` is deprecated (DEP0190), so the whole command is passed as one string there
+ * (args are fixed/allowlisted, never raw user input). POSIX spawns directly.
+ */
+export function run(cmd: string, args: string[], cwd: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+        const onWindows = process.platform === 'win32';
+        const child = onWindows
+            ? spawn([cmd, ...args].join(' '), { cwd, stdio: 'ignore', shell: true })
+            : spawn(cmd, args, { cwd, stdio: 'ignore' });
+        child.on('error', reject);
+        child.on('close', (code) =>
+            code === 0 ? resolve() : reject(new Error(`${cmd} exited with code ${String(code)}`)),
+        );
+    });
+}

package/src/cli/ui.ts

@@ -12,9 +12,9 @@ import pc from 'picocolors';
 type RGB = readonly [number, number, number];
 
 /** toiljs brand palette. */
-const PRIMARY: RGB = [37, 99, 255]; // #2563FF
-const SECONDARY: RGB = [124, 58, 237]; // #7C3AED
-const ACCENT: RGB = [34, 227, 171]; // #22E3AB
+const PRIMARY: RGB = [37, 99, 255];
+const SECONDARY: RGB = [124, 58, 237];
+const ACCENT: RGB = [34, 227, 171];
 
 /** Logo gradient stops: blue → purple → teal. */
 const GRADIENT: readonly RGB[] = [PRIMARY, SECONDARY, ACCENT];
@@ -90,9 +90,7 @@ export function version(): string {
         const raw = fs.readFileSync(pkgPath, 'utf8');
         const match = /"version"\s*:\s*"([^"]+)"/.exec(raw);
         if (match && match[1]) return match[1];
-    } catch {
-        /* fall through to default */
-    }
+    } catch {}
     return '0.0.0';
 }
 

package/src/cli/validate.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure input validation for `toiljs create` — kept dependency-light (only node:path) so it can be
+ * unit-tested without pulling in the rest of the CLI.
+ */
+import path from 'node:path';
+
+/** Package managers the scaffolder may invoke. Allowlisted so a hostile `--pm` can't inject a shell command. */
+export const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
+
+/** Validates a project name's characters. Returns `true`, or an error message. */
+export function isValidName(name: string): true | string {
+    if (!name.trim()) return 'Please enter a project name.';
+    if (!/^[a-z0-9._@/-]+$/i.test(name)) return 'Use letters, numbers, dashes, dots or slashes.';
+    return true;
+}
+
+/**
+ * Resolves `name` to an absolute directory under `cwd`, refusing to escape it (a name like
+ * `../x` or an absolute path). Returns the resolved dir, or `null` if it would escape `cwd`.
+ */
+export function resolveProjectDir(cwd: string, name: string): string | null {
+    const target = path.resolve(cwd, name);
+    const rel = path.relative(cwd, target);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) return null;
+    return target;
+}
+
+/** Whether `pm` is a supported package manager (guards shell use of `--pm`). */
+export function isPackageManager(pm: string): boolean {
+    return PACKAGE_MANAGERS.includes(pm);
+}

package/src/client/head/head.ts

@@ -0,0 +1,140 @@
+/**
+ * Client-side document `<head>` management. `useHead` / `useTitle` / `<Head>` let any component
+ * (layout or page) set the title and `<meta>` / `<link>` tags; entries compose across the tree
+ * (later/deeper entries win per key) and are reverted when the component unmounts. Pure
+ * `mergeHead` resolves the active entries; the manager reconciles `document.head`.
+ */
+import { useEffect } from 'react';
+
+/** A `<meta>` tag. Use `name` or `property` (OpenGraph) as the dedup key; extra attrs pass through. */
+export interface MetaTag {
+    readonly name?: string;
+    readonly property?: string;
+    readonly content: string;
+    readonly [attr: string]: string | undefined;
+}
+
+/** A `<link>` tag (deduped by `rel` + `href`); extra attrs pass through. */
+export interface LinkTag {
+    readonly rel: string;
+    readonly href: string;
+    readonly [attr: string]: string | undefined;
+}
+
+/** A head contribution from one component. */
+export interface HeadSpec {
+    /** Document title. */
+    readonly title?: string;
+    /** Template applied to a child's title, `%s` = the title (e.g. `'%s · toiljs'`). */
+    readonly titleTemplate?: string;
+    readonly meta?: readonly MetaTag[];
+    readonly link?: readonly LinkTag[];
+}
+
+/** The resolved head after merging all active specs. */
+export interface ResolvedHead {
+    readonly title?: string;
+    readonly meta: MetaTag[];
+    readonly link: LinkTag[];
+}
+
+function metaKey(m: MetaTag): string {
+    if (m.name !== undefined) return `name:${m.name}`;
+    if (m.property !== undefined) return `property:${m.property}`;
+    return `meta:${JSON.stringify(m)}`;
+}
+
+/**
+ * Merges head specs in order: the last `title`/`titleTemplate` wins, `meta` dedupes by name/property
+ * and `link` by rel+href (last wins). A `titleTemplate` formats the resolved title via `%s`.
+ */
+export function mergeHead(specs: readonly HeadSpec[]): ResolvedHead {
+    let title: string | undefined;
+    let titleTemplate: string | undefined;
+    const meta = new Map<string, MetaTag>();
+    const link = new Map<string, LinkTag>();
+    for (const spec of specs) {
+        if (spec.title !== undefined) title = spec.title;
+        if (spec.titleTemplate !== undefined) titleTemplate = spec.titleTemplate;
+        for (const m of spec.meta ?? []) meta.set(metaKey(m), m);
+        for (const l of spec.link ?? []) link.set(`${l.rel}:${l.href}`, l);
+    }
+    const resolvedTitle =
+        title !== undefined && titleTemplate !== undefined
+            ? titleTemplate.replace('%s', title)
+            : title;
+    return { title: resolvedTitle, meta: [...meta.values()], link: [...link.values()] };
+}
+
+const entries = new Map<number, HeadSpec>();
+let order: number[] = [];
+let seq = 0;
+let baseTitle: string | null = null;
+
+function setAttrs(el: Element, attrs: Record<string, string | undefined>): void {
+    el.setAttribute('data-toil-head', '');
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value !== undefined) el.setAttribute(key, value);
+    }
+}
+
+/** Reconciles `document.head` with the merged active specs. */
+function apply(): void {
+    if (typeof document === 'undefined') return;
+    if (baseTitle === null) baseTitle = document.title;
+
+    const resolved = mergeHead(order.map((id) => entries.get(id)).filter((s): s is HeadSpec => !!s));
+
+    document.title = resolved.title ?? baseTitle;
+
+    for (const stale of document.head.querySelectorAll('[data-toil-head]')) stale.remove();
+    for (const m of resolved.meta) {
+        const el = document.createElement('meta');
+        setAttrs(el, m);
+        document.head.appendChild(el);
+    }
+    for (const l of resolved.link) {
+        const el = document.createElement('link');
+        setAttrs(el, l);
+        document.head.appendChild(el);
+    }
+}
+
+function addHead(spec: HeadSpec): number {
+    const id = ++seq;
+    entries.set(id, spec);
+    order.push(id);
+    apply();
+    return id;
+}
+
+function removeHead(id: number): void {
+    entries.delete(id);
+    order = order.filter((x) => x !== id);
+    apply();
+}
+
+/**
+ * Applies a head contribution for the lifetime of the calling component: title, `<meta>`, `<link>`.
+ * Reverts on unmount. Compose freely — a root layout can set defaults a page overrides.
+ */
+export function useHead(spec: HeadSpec): void {
+    const json = JSON.stringify(spec);
+    useEffect(() => {
+        const id = addHead(JSON.parse(json) as HeadSpec);
+        return () => {
+            removeHead(id);
+        };
+    }, [json]);
+}
+
+/** Sets `document.title` for the calling component's lifetime. */
+export function useTitle(title: string): void {
+    useHead({ title });
+}
+
+/** Declarative form of {@link useHead}: `<Head title="…" meta={[…]} />`. Renders nothing. */
+export function Head(props: HeadSpec): null {
+    useHead(props);
+    return null;
+}

package/src/client/index.ts

@@ -1,12 +1,42 @@
 /**
- * toiljs client runtime, published as `toiljs/client`. Provides the router (mount/Router/Link),
- * navigation hooks, and route types consumed by the compiler-generated entry. Zero imports
- * needed in user route files beyond this package.
+ * toiljs client runtime, published as `toiljs/client`. Re-exports the router (mount/Router/Link),
+ * navigation hooks, prefetching, and the route types consumed by the compiler-generated entry.
+ * Zero imports needed in user route files beyond this package.
+ *
+ * Internals are split by concern: route `types`, history-based `navigation`, the params
+ * `params-context` + `hooks`, `lazy` component resolution, the `Link`/`Router` components,
+ * `mount`, `match` (pure matcher), `prefetch` (link prefetcher), and `channel` (WebSocket helper).
  */
 
-export { mount, Router, Link, navigate, useParams, useNavigate, useLocation } from './runtime.js';
-export type { RouteDef, LayoutLoader, NotFoundLoader } from './runtime.js';
-export { matchRoute } from './match.js';
-export type { RouteParams } from './match.js';
-export { connectChannel, useChannel, resolveChannelUrl } from './channel.js';
-export type { Channel, ChannelOptions, ChannelHook, ChannelData } from './channel.js';
+export { mount } from './routing/mount.js';
+export { Router } from './routing/Router.js';
+export { Link } from './navigation/Link.js';
+export type { LinkProps } from './navigation/Link.js';
+export { NavLink, matchActive } from './navigation/NavLink.js';
+export type { NavLinkProps, NavLinkState } from './navigation/NavLink.js';
+export { navigate, back, forward, refresh } from './navigation/navigation.js';
+export type { NavigateOptions } from './navigation/navigation.js';
+export {
+    useParams,
+    useNavigate,
+    useLocation,
+    usePathname,
+    useSearchParams,
+    useRouter,
+    useNavigationPending,
+} from './routing/hooks.js';
+export type { RouterInstance } from './routing/hooks.js';
+export { prefetch } from './navigation/prefetch.js';
+export type {
+    RouteDef,
+    LayoutLoader,
+    LayoutComponentLoader,
+    NotFoundLoader,
+    RouteErrorProps,
+} from './types.js';
+export { matchRoute } from './routing/match.js';
+export type { RouteParams } from './routing/match.js';
+export { connectChannel, useChannel, resolveChannelUrl } from './channel/channel.js';
+export type { Channel, ChannelOptions, ChannelHook, ChannelData } from './channel/channel.js';
+export { useHead, useTitle, Head, mergeHead } from './head/head.js';
+export type { HeadSpec, MetaTag, LinkTag, ResolvedHead } from './head/head.js';

package/src/client/navigation/Link.tsx

@@ -0,0 +1,99 @@
+import type {
+    ComponentPropsWithRef,
+    FocusEvent,
+    MouseEvent,
+    PointerEvent,
+    ReactNode,
+} from 'react';
+
+import { navigate } from './navigation.js';
+import { prefetch } from './prefetch.js';
+
+/**
+ * Props for {@link Link}: every standard `<a>` attribute (`rel`, `target`, `download`,
+ * `referrerPolicy`, `hrefLang`, `className`, `style`, `ref`, `data-*`, `aria-*`, event handlers …)
+ * plus toil's `replace` and `prefetch` controls. `href` is required.
+ */
+export interface LinkProps extends Omit<ComponentPropsWithRef<'a'>, 'href'> {
+    /** Destination. Same-origin hrefs navigate client-side; external / `target` / `download` / `#hash` use the browser. */
+    href: string;
+    /** Replace the current history entry instead of pushing a new one. Default `false`. */
+    replace?: boolean;
+    /** Scroll to top after navigating. Default `true`. */
+    scroll?: boolean;
+    /** Prefetch the route chunk on hover/focus. Default `true`; `false` opts this link out. */
+    prefetch?: boolean;
+}
+
+/** True for cross-origin, opaque (`mailto:` / `tel:`), or otherwise non-same-origin hrefs. */
+function isExternalHref(href: string): boolean {
+    try {
+        return new URL(href, window.location.href).origin !== window.location.origin;
+    } catch {
+        return true;
+    }
+}
+
+/**
+ * Client-side navigation link. Forwards all anchor attributes to the underlying `<a>`, and
+ * prefetches the target route's chunk on hover/focus. Intercepts only plain same-origin clicks —
+ * modified clicks, `target=_blank`, `download`, in-page `#hash`, and external URLs fall through to
+ * native browser behavior.
+ */
+export function Link(props: LinkProps): ReactNode {
+    const {
+        href,
+        replace = false,
+        scroll = true,
+        prefetch: prefetchProp = true,
+        onClick,
+        onPointerEnter,
+        onFocus,
+        children,
+        ...rest
+    } = props;
+
+    const handleClick = (event: MouseEvent<HTMLAnchorElement>): void => {
+        onClick?.(event);
+        if (
+            event.defaultPrevented ||
+            event.button !== 0 ||
+            event.metaKey ||
+            event.ctrlKey ||
+            event.shiftKey ||
+            event.altKey ||
+            (rest.target !== undefined && rest.target !== '_self') ||
+            rest.download !== undefined ||
+            href.startsWith('#') ||
+            isExternalHref(href)
+        ) {
+            return;
+        }
+        event.preventDefault();
+        navigate(href, { replace, scroll });
+    };
+
+    const warm = (): void => {
+        if (prefetchProp) prefetch(href);
+    };
+    const handlePointerEnter = (event: PointerEvent<HTMLAnchorElement>): void => {
+        onPointerEnter?.(event);
+        warm();
+    };
+    const handleFocus = (event: FocusEvent<HTMLAnchorElement>): void => {
+        onFocus?.(event);
+        warm();
+    };
+
+    return (
+        <a
+            {...rest}
+            {...(prefetchProp ? {} : { 'data-no-prefetch': '' })}
+            href={href}
+            onClick={handleClick}
+            onPointerEnter={handlePointerEnter}
+            onFocus={handleFocus}>
+            {children}
+        </a>
+    );
+}

package/src/client/navigation/NavLink.tsx

@@ -0,0 +1,86 @@
+import type { CSSProperties, ReactNode } from 'react';
+
+import { useLocation } from '../routing/hooks.js';
+import { Link, type LinkProps } from './Link.js';
+
+/** State passed to `NavLink`'s function-form `className` / `style` / `children`. */
+export interface NavLinkState {
+    readonly isActive: boolean;
+}
+
+/**
+ * Props for {@link NavLink}: all {@link LinkProps}, but `className` / `style` / `children` may also
+ * be functions of the active state.
+ */
+export interface NavLinkProps extends Omit<LinkProps, 'className' | 'style' | 'children'> {
+    className?: string | ((state: NavLinkState) => string | undefined);
+    style?: CSSProperties | ((state: NavLinkState) => CSSProperties | undefined);
+    children?: ReactNode | ((state: NavLinkState) => ReactNode);
+    /** Match `href` exactly; without it, sub-paths are also active. Default `false`. */
+    end?: boolean;
+    /** Class added when active (used with a string `className`). Default `"active"`. */
+    activeClassName?: string;
+}
+
+function normalizePath(p: string): string {
+    return p.length > 1 ? p.replace(/\/+$/, '') : p;
+}
+
+/**
+ * Whether a link to `linkPath` is active for `currentPath`. Exact when `end`; otherwise a parent
+ * path is active for its sub-paths (and `/` is active everywhere, matching React Router).
+ */
+export function matchActive(linkPath: string, currentPath: string, end: boolean): boolean {
+    const link = normalizePath(linkPath);
+    const current = normalizePath(currentPath);
+    if (current === link) return true;
+    if (end) return false;
+    if (link === '/') return true;
+    return current.startsWith(link + '/');
+}
+
+/**
+ * A {@link Link} that knows whether it points at the current location. Applies an active class
+ * (default `"active"`) and `aria-current="page"` when active; `className` / `style` / `children`
+ * may be functions of `{ isActive }`. Inherits Link's full anchor API and prefetching.
+ */
+export function NavLink(props: NavLinkProps): ReactNode {
+    const {
+        href,
+        className,
+        style,
+        children,
+        end = false,
+        activeClassName = 'active',
+        ...rest
+    } = props;
+    const pathname = useLocation();
+
+    let linkPath = href;
+    try {
+        linkPath = new URL(href, window.location.href).pathname;
+    } catch {
+        linkPath = href;
+    }
+    const isActive = matchActive(linkPath, pathname, end);
+    const state: NavLinkState = { isActive };
+
+    const resolvedClassName =
+        typeof className === 'function'
+            ? className(state)
+            : [className, isActive ? activeClassName : undefined].filter(Boolean).join(' ') ||
+              undefined;
+    const resolvedStyle = typeof style === 'function' ? style(state) : style;
+    const resolvedChildren = typeof children === 'function' ? children(state) : children;
+
+    return (
+        <Link
+            {...rest}
+            href={href}
+            className={resolvedClassName}
+            style={resolvedStyle}
+            aria-current={isActive ? 'page' : undefined}>
+            {resolvedChildren}
+        </Link>
+    );
+}