@loadbare/app 0.4.0

package/dist/build/locations.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Finding every file a build needs by what it's named, not by which
+ * directory it happens to sit in.
+ *
+ * A page and a widget definition can be byte-for-byte identical markup —
+ * the only thing that says which one a file is, is extrinsic to its
+ * content. `pages/` vs. `widgets/` used to carry that meaning; here a
+ * filename suffix does instead: `*.chrome.html` is the one chrome file,
+ * `*.page.html` is a page, and anything else `.html` is a widget
+ * definition. A `.ts` file shaped like a custom element tag is a widget
+ * script, found the same way regardless of where it lives. Both halves of
+ * one widget — its markup and its class — are free to sit side by side or
+ * apart; nothing here requires a `widgets/` directory to exist at all.
+ *
+ * A page's server half is named the same way: `*.hooks.ts` and
+ * `*.queries.ts` pair with a `*.page.html` by sharing its basename, and are
+ * free to sit anywhere too. Either may be absent — a page with no data needs
+ * neither — but one with no matching `*.page.html` is a naming mistake and
+ * is rejected below.
+ *
+ * A `.css` file is not paired with anything — it is not a widget's, a
+ * page's, or the chrome's, because build/styles.ts does not distinguish
+ * them. Every `.css` file anywhere under `src` is concatenated, in an order
+ * controlled entirely by the author: sorted by filename first, so a global
+ * stylesheet sorts to the front by naming itself `00-reset.css` or similar,
+ * regardless of which directory it lives in.
+ *
+ * `--src` names the one tree scanned this way; `--out` names where the
+ * build lands. Those, plus this package's own root (for its built-in
+ * widgets and hub/), are the only locations this module resolves — every
+ * other module takes the result as a plain parameter and never
+ * reconstructs one of its own.
+ */
+/** Lowercase, hyphenated — the one shape every custom element tag has, and the one native elements never do. */
+export declare const CUSTOM_ELEMENT_TAG: RegExp;
+export interface PageFile {
+    name: string;
+    file: string;
+}
+export interface WidgetSource {
+    /** Absolute path to the `.html` definition, if this tag has one. */
+    html?: string;
+    /** Absolute path, without extension, to the `.ts` script, if this tag has one. */
+    script?: string;
+}
+export interface PageSource {
+    /** Absolute path, without extension, to the `.hooks.ts` module, if this page has one. */
+    hooks?: string;
+    /** Absolute path, without extension, to the `.queries.ts` module, if this page has one. */
+    queries?: string;
+}
+interface Discovered {
+    chromeCandidates: string[];
+    pages: PageFile[];
+    pageSources: Map<string, PageSource>;
+    widgets: Map<string, WidgetSource>;
+    elementsCandidates: string[];
+    cssFiles: string[];
+}
+/** The raw walk, with no uniqueness checks — usable on its own by anything that does not need a chrome file. */
+export declare function discoverSrc(src: string): Promise<Discovered>;
+export interface PackageInfo {
+    /** This package's own widgets/ — the built-in widget definitions and classes. */
+    builtinWidgetsDir: string;
+    /** This package's own hub/ — where lb-hub's script lives, found the same way as any built-in widget. */
+    builtinHubDir: string;
+    /** This package's own name, e.g. "@loadbare/app" — for naming a built-in's import specifier. */
+    packageName: string;
+}
+export declare function packageInfo(): Promise<PackageInfo>;
+export interface LocationArgs {
+    /** The application's source tree, e.g. "src". Scanned as a whole — see this file's header. */
+    src: string;
+    out: string;
+}
+export interface Locations extends PackageInfo {
+    chromeFile: string;
+    pages: PageFile[];
+    pageSources: Map<string, PageSource>;
+    widgets: Map<string, WidgetSource>;
+    elementsFile?: string;
+    cssFiles: string[];
+    outDir: string;
+}
+export declare function resolveLocations(args: LocationArgs): Promise<Locations>;
+export {};
+//# sourceMappingURL=locations.d.ts.map

package/dist/build/locations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locations.d.ts","sourceRoot":"","sources":["../../build/locations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAQH,gHAAgH;AAChH,eAAO,MAAM,kBAAkB,QAAkC,CAAC;AASlE,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,UAAU;IAClB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACnC,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,gHAAgH;AAChH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CA+ElE;AAED,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wGAAwG;IACxG,aAAa,EAAE,MAAM,CAAC;IACtB,gGAAgG;IAChG,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAiBxD;AAED,MAAM,WAAW,YAAY;IAC3B,8FAA8F;IAC9F,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC5C,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAoD7E"}

package/dist/build/locations.js

@@ -0,0 +1,173 @@
+/**
+ * Finding every file a build needs by what it's named, not by which
+ * directory it happens to sit in.
+ *
+ * A page and a widget definition can be byte-for-byte identical markup —
+ * the only thing that says which one a file is, is extrinsic to its
+ * content. `pages/` vs. `widgets/` used to carry that meaning; here a
+ * filename suffix does instead: `*.chrome.html` is the one chrome file,
+ * `*.page.html` is a page, and anything else `.html` is a widget
+ * definition. A `.ts` file shaped like a custom element tag is a widget
+ * script, found the same way regardless of where it lives. Both halves of
+ * one widget — its markup and its class — are free to sit side by side or
+ * apart; nothing here requires a `widgets/` directory to exist at all.
+ *
+ * A page's server half is named the same way: `*.hooks.ts` and
+ * `*.queries.ts` pair with a `*.page.html` by sharing its basename, and are
+ * free to sit anywhere too. Either may be absent — a page with no data needs
+ * neither — but one with no matching `*.page.html` is a naming mistake and
+ * is rejected below.
+ *
+ * A `.css` file is not paired with anything — it is not a widget's, a
+ * page's, or the chrome's, because build/styles.ts does not distinguish
+ * them. Every `.css` file anywhere under `src` is concatenated, in an order
+ * controlled entirely by the author: sorted by filename first, so a global
+ * stylesheet sorts to the front by naming itself `00-reset.css` or similar,
+ * regardless of which directory it lives in.
+ *
+ * `--src` names the one tree scanned this way; `--out` names where the
+ * build lands. Those, plus this package's own root (for its built-in
+ * widgets and hub/), are the only locations this module resolves — every
+ * other module takes the result as a plain parameter and never
+ * reconstructs one of its own.
+ */
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findPackageRoot } from "./package-root.js";
+/** Lowercase, hyphenated — the one shape every custom element tag has, and the one native elements never do. */
+export const CUSTOM_ELEMENT_TAG = /^[a-z][a-z0-9]*(-[a-z0-9]+)+$/;
+const CHROME_SUFFIX = ".chrome.html";
+const PAGE_SUFFIX = ".page.html";
+const HOOKS_SUFFIX = ".hooks.ts";
+const QUERIES_SUFFIX = ".queries.ts";
+const CSS_SUFFIX = ".css";
+const ELEMENTS_FILENAME = "elements.ts";
+/** The raw walk, with no uniqueness checks — usable on its own by anything that does not need a chrome file. */
+export async function discoverSrc(src) {
+    const chromeCandidates = [];
+    const pages = [];
+    const pageSources = new Map();
+    const widgets = new Map();
+    const elementsCandidates = [];
+    const cssFiles = [];
+    let entries;
+    try {
+        entries = await readdir(src, { withFileTypes: true, recursive: true });
+    }
+    catch {
+        entries = [];
+    }
+    const widget = (tag) => {
+        let w = widgets.get(tag);
+        if (!w) {
+            w = {};
+            widgets.set(tag, w);
+        }
+        return w;
+    };
+    const pageSource = (name) => {
+        let p = pageSources.get(name);
+        if (!p) {
+            p = {};
+            pageSources.set(name, p);
+        }
+        return p;
+    };
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const file = path.join(entry.parentPath, entry.name);
+        if (entry.name === ELEMENTS_FILENAME) {
+            elementsCandidates.push(file);
+        }
+        else if (entry.name.endsWith(CHROME_SUFFIX)) {
+            chromeCandidates.push(file);
+        }
+        else if (entry.name.endsWith(PAGE_SUFFIX)) {
+            pages.push({ name: entry.name.slice(0, -PAGE_SUFFIX.length), file });
+        }
+        else if (entry.name.endsWith(HOOKS_SUFFIX)) {
+            pageSource(entry.name.slice(0, -HOOKS_SUFFIX.length)).hooks = file.slice(0, -".ts".length);
+        }
+        else if (entry.name.endsWith(QUERIES_SUFFIX)) {
+            pageSource(entry.name.slice(0, -QUERIES_SUFFIX.length)).queries =
+                file.slice(0, -".ts".length);
+        }
+        else if (entry.name.endsWith(CSS_SUFFIX)) {
+            cssFiles.push(file);
+        }
+        else if (entry.name.endsWith(".html")) {
+            widget(entry.name.slice(0, -".html".length).toLowerCase()).html = file;
+        }
+        else if (entry.name.endsWith(".ts")) {
+            const tag = entry.name.slice(0, -".ts".length).toLowerCase();
+            // Without the extension: this becomes an import specifier, and esbuild
+            // resolves ".ts" from the bare path the same way it resolves ".js".
+            if (CUSTOM_ELEMENT_TAG.test(tag))
+                widget(tag).script = file.slice(0, -".ts".length);
+        }
+    }
+    pages.sort((a, b) => a.name.localeCompare(b.name));
+    // By filename first, full path only to break a tie — see this file's
+    // header. A directory a file happens to sit in never affects the order.
+    cssFiles.sort((a, b) => path.basename(a).localeCompare(path.basename(b)) || a.localeCompare(b));
+    return {
+        chromeCandidates,
+        pages,
+        pageSources,
+        widgets,
+        elementsCandidates,
+        cssFiles,
+    };
+}
+export async function packageInfo() {
+    const root = await findPackageRoot(path.dirname(fileURLToPath(import.meta.url)));
+    let pkg;
+    try {
+        pkg = JSON.parse(await readFile(path.join(root, "package.json"), "utf-8"));
+    }
+    catch (err) {
+        throw new Error(`locations: could not read '${root}/package.json': ${err.message}`);
+    }
+    return {
+        builtinWidgetsDir: path.join(root, "widgets"),
+        builtinHubDir: path.join(root, "hub"),
+        packageName: pkg.name,
+    };
+}
+export async function resolveLocations(args) {
+    const [info, discovered] = await Promise.all([
+        packageInfo(),
+        discoverSrc(args.src),
+    ]);
+    const { chromeCandidates, elementsCandidates, pages, pageSources, widgets, cssFiles, } = discovered;
+    if (chromeCandidates.length === 0) {
+        throw new Error(`locations: no *${CHROME_SUFFIX} file found under '${args.src}'`);
+    }
+    if (chromeCandidates.length > 1) {
+        throw new Error(`locations: more than one *${CHROME_SUFFIX} file found under '${args.src}': ` +
+            chromeCandidates.join(", "));
+    }
+    if (elementsCandidates.length > 1) {
+        throw new Error(`locations: more than one ${ELEMENTS_FILENAME} found under '${args.src}': ` +
+            elementsCandidates.join(", "));
+    }
+    const pageNames = new Set(pages.map((p) => p.name));
+    for (const name of pageSources.keys()) {
+        if (!pageNames.has(name)) {
+            throw new Error(`locations: '${name}${HOOKS_SUFFIX}' or '${name}${QUERIES_SUFFIX}' found under ` +
+                `'${args.src}' but there is no '${name}${PAGE_SUFFIX}'`);
+        }
+    }
+    return {
+        ...info,
+        chromeFile: chromeCandidates[0],
+        pages,
+        pageSources,
+        widgets,
+        elementsFile: elementsCandidates[0],
+        cssFiles,
+        outDir: args.out,
+    };
+}

package/dist/build/package-root.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Walk up from `dir` to the nearest ancestor holding a package.json.
+ *
+ * Needed because a caller may run from source (build/*.ts) or compiled
+ * (dist/build/*.js) — both are the same distance from the package root, but
+ * nothing here should assume that stays true.
+ */
+export declare function findPackageRoot(dir: string): Promise<string>;
+//# sourceMappingURL=package-root.d.ts.map

package/dist/build/package-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-root.d.ts","sourceRoot":"","sources":["../../build/package-root.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAalE"}

package/dist/build/package-root.js

@@ -0,0 +1,24 @@
+/**
+ * Walk up from `dir` to the nearest ancestor holding a package.json.
+ *
+ * Needed because a caller may run from source (build/*.ts) or compiled
+ * (dist/build/*.js) — both are the same distance from the package root, but
+ * nothing here should assume that stays true.
+ */
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+export async function findPackageRoot(dir) {
+    for (;;) {
+        try {
+            await readFile(path.join(dir, "package.json"), "utf-8");
+            return dir;
+        }
+        catch {
+            const parent = path.dirname(dir);
+            if (parent === dir) {
+                throw new Error(`could not find a package.json above '${dir}'`);
+            }
+            dir = parent;
+        }
+    }
+}

package/dist/build/pages.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Generating the hub's page registry — the server-side counterpart to
+ * build/elements.ts's client entry point.
+ *
+ * `*.hooks.ts` and `*.queries.ts` are ordinary TypeScript, found by
+ * build/locations.ts and handed here already paired by page name. What this
+ * module writes is the file an application used to hand-maintain: an import
+ * of each pair, a `Pages` object naming them by page, and the one
+ * `createHub()` call. It is written to `<out>/pages.ts` rather than compiled
+ * — the application runs it directly, exactly as it does its own server
+ * code, so it never needs a bundler step the way the browser-bound client
+ * entry does.
+ *
+ * Nothing here is emitted for a page with neither a hooks nor a queries
+ * file — a purely static page needs no hub entry, and createHub is only
+ * called at all when there is at least one.
+ */
+import type { PageFile, PageSource } from "./locations.js";
+/**
+ * `undefined` when no page has a hooks or queries file — the caller writes
+ * nothing in that case, the same way an app with no custom elements gets no
+ * client entry beyond the built-ins.
+ */
+export declare function pagesSource(pages: PageFile[], pageSources: Map<string, PageSource>, outDir: string, packageName: string): string | undefined;
+//# sourceMappingURL=pages.d.ts.map

package/dist/build/pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../../build/pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAY3D;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,QAAQ,EAAE,EACjB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACpC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,MAAM,GAAG,SAAS,CAoCpB"}

package/dist/build/pages.js

@@ -0,0 +1,54 @@
+/**
+ * Generating the hub's page registry — the server-side counterpart to
+ * build/elements.ts's client entry point.
+ *
+ * `*.hooks.ts` and `*.queries.ts` are ordinary TypeScript, found by
+ * build/locations.ts and handed here already paired by page name. What this
+ * module writes is the file an application used to hand-maintain: an import
+ * of each pair, a `Pages` object naming them by page, and the one
+ * `createHub()` call. It is written to `<out>/pages.ts` rather than compiled
+ * — the application runs it directly, exactly as it does its own server
+ * code, so it never needs a bundler step the way the browser-bound client
+ * entry does.
+ *
+ * Nothing here is emitted for a page with neither a hooks nor a queries
+ * file — a purely static page needs no hub entry, and createHub is only
+ * called at all when there is at least one.
+ */
+import path from "node:path";
+/** A page name may contain anything a filename can; an import identifier may not. */
+function identifier(name, suffix) {
+    return `page_${name.replace(/[^a-zA-Z0-9]/g, "_")}_${suffix}`;
+}
+function relativeImport(outDir, file) {
+    const rel = path.relative(outDir, file).split(path.sep).join("/");
+    return rel.startsWith(".") ? rel : `./${rel}`;
+}
+/**
+ * `undefined` when no page has a hooks or queries file — the caller writes
+ * nothing in that case, the same way an app with no custom elements gets no
+ * client entry beyond the built-ins.
+ */
+export function pagesSource(pages, pageSources, outDir, packageName) {
+    if (pageSources.size === 0)
+        return undefined;
+    const imports = [
+        `import { createHub } from ${JSON.stringify(`${packageName}/server`)};`,
+    ];
+    const entries = [];
+    for (const { name } of pages) {
+        const source = pageSources.get(name);
+        if (!source)
+            continue;
+        const hooksId = source.hooks ? identifier(name, "Hooks") : undefined;
+        const queriesId = source.queries ? identifier(name, "Queries") : undefined;
+        if (source.hooks) {
+            imports.push(`import { hooks as ${hooksId} } from ${JSON.stringify(relativeImport(outDir, source.hooks))};`);
+        }
+        if (source.queries) {
+            imports.push(`import { queries as ${queriesId} } from ${JSON.stringify(relativeImport(outDir, source.queries))};`);
+        }
+        entries.push(`  ${JSON.stringify(name)}: { hooks: ${hooksId ?? "{}"}, queries: ${queriesId ?? "{}"} },`);
+    }
+    return ([...imports, "", "export const hub = createHub({", ...entries, "});"].join("\n") + "\n");
+}

package/dist/build/styles.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Concatenating an application's CSS.
+ *
+ * There is no widget, page, or chrome concept here — every `.css` file
+ * anywhere under `src` is joined, in the order build/locations.ts already
+ * sorted them into, with nothing added, removed, or scoped. What ships is
+ * exactly the concatenation of what was authored, the same "view source is
+ * what ships" rule build/assemble.ts holds for markup. Ordering is the
+ * author's own, by filename — see build/locations.ts for the convention.
+ */
+/** `undefined` when there is no CSS at all — the caller writes nothing in that case. */
+export declare function stylesSource(cssFiles: string[]): Promise<string | undefined>;
+//# sourceMappingURL=styles.d.ts.map

package/dist/build/styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../build/styles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,wFAAwF;AACxF,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM7B"}

package/dist/build/styles.js

@@ -0,0 +1,18 @@
+/**
+ * Concatenating an application's CSS.
+ *
+ * There is no widget, page, or chrome concept here — every `.css` file
+ * anywhere under `src` is joined, in the order build/locations.ts already
+ * sorted them into, with nothing added, removed, or scoped. What ships is
+ * exactly the concatenation of what was authored, the same "view source is
+ * what ships" rule build/assemble.ts holds for markup. Ordering is the
+ * author's own, by filename — see build/locations.ts for the convention.
+ */
+import { readFile } from "node:fs/promises";
+/** `undefined` when there is no CSS at all — the caller writes nothing in that case. */
+export async function stylesSource(cssFiles) {
+    if (cssFiles.length === 0)
+        return undefined;
+    const parts = await Promise.all(cssFiles.map((file) => readFile(file, "utf-8")));
+    return parts.join("\n");
+}