@pantoken/scaffold-base 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Danny Wahl
+
+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,31 @@
+# @pantoken/scaffold-base
+
+The shared [`bingo-stratum`](https://www.create.bingo/engines/stratum) `Base` every pantoken scaffold
+platform Preset is built from. Provides:
+
+- **Common options schema**: `projectName` string with `"pantoken-app"` default.
+- **Shared Blocks**: `blockCssdoc` (writes `cssdoc.json`), `blockWrapperContext` (provides markup derived
+  from [`@pantoken/plugin-layouts`](https://www.npmjs.com/package/@pantoken/plugin-layouts)'s `wrapper`
+  app-shell layout for platform-specific rendering).
+- **Factory function**: `createPreset()` for type-safe Preset construction with `--isolatedDeclarations`
+  compatibility.
+
+Used by platform packages (`@pantoken/components`, `@pantoken/react`, `@pantoken/vue`,
+`@pantoken/web-components`) to define their own presets, which are then auto-discovered and
+registered by [`@pantoken/scaffold`](https://www.npmjs.com/package/@pantoken/scaffold).
+
+Not meant to be used standalone — see `@pantoken/scaffold` for the full scaffolding workflow.
+
+## API
+
+- **`base`** — the shared `bingo-stratum` `Base`, exported for re-use in platform presets.
+- **`createPreset(input)`** — factory function constructing a type-safe `Preset` with platform-specific
+  options. Workaround for `--isolatedDeclarations` mode, which requires explicit types on all exports.
+- **`blockCssdoc`** — a `Base`-scoped Block that writes the shared `cssdoc.json` scaffold file.
+- **`getWrapperContext()`** — returns `{ wrapperRootClass, wrapperContainerHtml(depth?), wrapperContainerJsx(depth?) }`,
+  derived from the `wrapper` app-shell layout, for use as Handlebars context in a platform's own
+  templates.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,50 @@
+import { Base, BlockWithoutAddons, Preset, Preset as Preset$1 } from "bingo-stratum";
+import { z } from "zod";
+//#region src/base.d.ts
+declare const options: {
+  name: z.ZodDefault<z.ZodString>;
+};
+/** Shared options every pantoken scaffold platform Preset takes in. */
+declare const base: Base<typeof options>;
+//#endregion
+//#region src/preset.d.ts
+interface PresetInput {
+  name: string;
+  base: Base<any>;
+  blocks?: any[];
+}
+/**
+ * Create a scaffold Preset with explicit return type for TypeScript `--isolatedDeclarations`.
+ *
+ * @param input - Preset configuration with name, base, and optional blocks
+ * @returns Properly typed Bingo Preset
+ */
+declare function createPreset(input: PresetInput): Preset$1;
+//#endregion
+//#region src/blocks/cssdoc.d.ts
+/** Writes the shared `cssdoc.json` schema file, unmodified by platform or options. */
+declare const blockCssdoc: BlockWithoutAddons<{
+  name: string;
+}>;
+//#endregion
+//#region src/wrapper-context.d.ts
+/**
+ * Render the wrapper layout's `.container` part tree as markup, starting at the given indent depth.
+ * `format: "html"` covers plain HTML/Angular templates (`class="..."`); `"jsx"` covers React/Next
+ * (`className="..."`).
+ */
+declare function renderWrapperContainer(format: "html" | "jsx", depth?: number): string;
+/** The wrapper layout's root class name (applied to the real document `<body>` or component root). */
+declare function wrapperRootClassName(): string;
+/**
+ * The wrapper layout markup/tokens every platform Preset feeds into its own Handlebars context —
+ * `{{projectName}}` inside the rendered markup is left as-is, for the platform's own template to
+ * resolve.
+ */
+declare function getWrapperContext(): {
+  wrapperRootClass: string;
+  wrapperContainerHtml: (depth?: number) => string;
+  wrapperContainerJsx: (depth?: number) => string;
+};
+//#endregion
+export { type Preset, base, blockCssdoc, createPreset, getWrapperContext, renderWrapperContainer, wrapperRootClassName };

package/dist/index.mjs

@@ -0,0 +1,196 @@
+import { createBase } from "bingo-stratum";
+import { z } from "zod";
+import { wrapperRules } from "@pantoken/plugin-layouts";
+//#region src/base.ts
+const options = { name: z.string().default("pantoken-app").describe("Name of the scaffolded project") };
+/** Shared options every pantoken scaffold platform Preset takes in. */
+const base = createBase({ options });
+//#endregion
+//#region src/preset.ts
+/**
+* Create a scaffold Preset with explicit return type for TypeScript `--isolatedDeclarations`.
+*
+* @param input - Preset configuration with name, base, and optional blocks
+* @returns Properly typed Bingo Preset
+*/
+function createPreset(input) {
+	return {
+		about: { name: input.name },
+		base: input.base,
+		blocks: input.blocks ?? []
+	};
+}
+//#endregion
+//#region generated/cssdoc.ts
+const CSSDOC_JSON = "{\n  \"$schema\": \"https://cssdoc.dev/cssdoc.schema.json\",\n  \"extends\": [\"./node_modules/@pantoken/pantoken/cssdoc-base.json\"],\n  \"modifierConvention\": \"rscss\",\n  \"inlineComments\": \"ignore\",\n  // This provider resolves pantoken's documented components/utilities for lint/hover/completions. It\n  // assumes the default \"instui-\" class prefix pantoken ships with — if you build your OWN pantoken\n  // CSS with a different prefix spelling (e.g. componentsCss({ prefix: \"acme\" })), rewrite it here.\n  // `to` is used verbatim — no \"-\" is assumed or added, so match whatever you actually built with:\n  //   \"prefix\": { \"from\": \"instui-\", \"to\": \"acme-\" }\n  // Built unprefixed (componentsCss({ prefix: null })) or with no separator (e.g. \"ialert\" instead of\n  // \"instui-alert\")? Set `to` to match exactly — omit it (or use \"\") to strip to a bare class:\n  //   \"prefix\": { \"from\": \"instui-\", \"to\": \"i\" }\n  \"providers\": [{ \"path\": \"./node_modules/@pantoken/pantoken/model.json\" }]\n}\n";
+//#endregion
+//#region src/blocks/cssdoc.ts
+/** Writes the shared `cssdoc.json` schema file, unmodified by platform or options. */
+const blockCssdoc = base.createBlock({
+	about: { name: "cssdoc" },
+	produce: () => ({ files: { "cssdoc.json": CSSDOC_JSON } })
+});
+//#endregion
+//#region src/wrapper-context.ts
+/**
+* Derives each scaffold platform's entry markup from `@pantoken/plugin-layouts`'s `wrapper` layout,
+* so every preset's template stays structurally in sync with that layout automatically. Called at
+* scaffold-produce-time (not build-time) — every platform preset feeds these values into its own
+* Handlebars context instead of hand-authoring the wrapper markup.
+*
+* @module
+* @alpha
+*/
+function extractSelector(raw) {
+	const lastSemi = raw.lastIndexOf(";");
+	return (lastSemi === -1 ? raw : raw.slice(lastSemi + 1)).trim();
+}
+/** Split CSS text into top-level (brace-depth-aware) rules, ignoring plain declarations. */
+function splitRules(css) {
+	const rules = [];
+	let depth = 0;
+	let selectorStart = 0;
+	let bodyStart = -1;
+	for (let i = 0; i < css.length; i++) {
+		const ch = css[i];
+		if (ch === "{") {
+			if (depth === 0) bodyStart = i + 1;
+			depth++;
+			continue;
+		}
+		if (ch !== "}") continue;
+		depth--;
+		if (depth !== 0 || bodyStart === -1) continue;
+		const selector = extractSelector(css.slice(selectorStart, bodyStart - 1));
+		if (selector) rules.push({
+			selector,
+			body: css.slice(bodyStart, i)
+		});
+		selectorStart = i + 1;
+		bodyStart = -1;
+	}
+	return rules;
+}
+/** Parse a single selector into a node shape (tag/class/attrs), or `null` for a `&`-scoped state rule. */
+function parseSelector(selector) {
+	if (selector.startsWith("@")) return {
+		tag: "",
+		comment: selector.replace(/^@component\s+/, "")
+	};
+	if (selector.startsWith("&")) return null;
+	const optional = selector.includes(":optional");
+	const attrMatch = /^([a-z]*)\[([\w-]+)(?:~|)=(?:"([^"]*)"|'([^']*)')\]/i.exec(selector);
+	if (attrMatch) {
+		const [, tag, attrName, dq, sq] = attrMatch;
+		const value = dq ?? sq ?? "";
+		if (attrName === "class") return {
+			tag: tag || "div",
+			className: value,
+			optional
+		};
+		return {
+			tag: tag || "div",
+			attrs: { [attrName]: value },
+			optional
+		};
+	}
+	const tagMatch = /^[a-z][a-z0-9]*/i.exec(selector);
+	const classMatch = /\.([\w-]+)/.exec(selector);
+	return {
+		tag: tagMatch?.[0] ?? "div",
+		className: classMatch?.[1],
+		optional
+	};
+}
+function parseNodes(css) {
+	const nodes = [];
+	for (const { selector, body } of splitRules(css)) for (const single of selector.split(",")) {
+		const parsed = parseSelector(single.trim());
+		if (!parsed) continue;
+		nodes.push({
+			...parsed,
+			children: parseNodes(body)
+		});
+	}
+	return nodes;
+}
+/** Strip the leading cssdoc block comment so it isn't parsed as a rule body. */
+function stripLeadingDocComment(css) {
+	const end = css.indexOf("*/");
+	return end === -1 ? css : css.slice(end + 2);
+}
+/** The wrapper layout's root class name and its `.container` node (everything the root wraps). */
+function parseWrapperLayout() {
+	const [root] = parseNodes(stripLeadingDocComment(wrapperRules()));
+	if (!root) throw new Error("wrapper layout: no root rule found");
+	const container = root.children.find((n) => n.className === "container");
+	if (!container) throw new Error("wrapper layout: no .container part found");
+	return {
+		rootClassName: root.className ?? "",
+		container
+	};
+}
+/** Placeholder text injected at specific parts, keyed by class name. */
+const PART_TEXT = {
+	title: "{{projectName}}",
+	description: "Styled with <code>@pantoken/components</code> and laid out with the <code>wrapper</code> layout from <code>@pantoken/plugin-layouts</code>."
+};
+/** The `slot[name="content"]` part gets the platform's actual getting-started content, per format. */
+const MAIN_CONTENT = {
+	html: "<p>Get started building with pantoken.</p>\n<button class=\"instui-button -color-primary\" type=\"button\">Get started</button>",
+	jsx: "<p>Get started building with pantoken.</p>\n<button className=\"instui-button -color-primary\" type=\"button\">Get started</button>"
+};
+function attrName(format) {
+	return format === "jsx" ? "className" : "class";
+}
+function comment(format, text) {
+	return format === "jsx" ? `{/* ${text} */}` : `<!-- ${text} -->`;
+}
+function renderNode(node, format, depth) {
+	const pad = "  ".repeat(depth);
+	if (node.comment) return `${pad}${comment(format, node.comment)}`;
+	const attrs = [];
+	if (node.className) attrs.push(`${attrName(format)}="${node.className}"`);
+	for (const [name, value] of Object.entries(node.attrs ?? {})) attrs.push(`${name}="${value}"`);
+	const openTag = `<${node.tag}${attrs.length ? ` ${attrs.join(" ")}` : ""}>`;
+	const closeTag = `</${node.tag}>`;
+	const optionalNote = node.optional ? ` ${comment(format, "optional")}` : "";
+	const isMainSlot = node.tag === "slot" && node.attrs?.name === "content";
+	const text = PART_TEXT[node.className ?? ""] ?? (isMainSlot ? MAIN_CONTENT[format] : void 0);
+	const childLines = node.children.map((child) => renderNode(child, format, depth + 1));
+	const bodyPad = "  ".repeat(depth + 1);
+	const bodyLines = text ? text.split("\n").map((line) => `${bodyPad}${line}`) : childLines;
+	if (bodyLines.length === 0) return `${pad}${openTag}${closeTag}${optionalNote}`;
+	return [
+		`${pad}${openTag}${optionalNote}`,
+		...bodyLines,
+		`${pad}${closeTag}`
+	].join("\n");
+}
+/**
+* Render the wrapper layout's `.container` part tree as markup, starting at the given indent depth.
+* `format: "html"` covers plain HTML/Angular templates (`class="..."`); `"jsx"` covers React/Next
+* (`className="..."`).
+*/
+function renderWrapperContainer(format, depth = 0) {
+	const { container } = parseWrapperLayout();
+	return renderNode(container, format, depth);
+}
+/** The wrapper layout's root class name (applied to the real document `<body>` or component root). */
+function wrapperRootClassName() {
+	return parseWrapperLayout().rootClassName;
+}
+/**
+* The wrapper layout markup/tokens every platform Preset feeds into its own Handlebars context —
+* `{{projectName}}` inside the rendered markup is left as-is, for the platform's own template to
+* resolve.
+*/
+function getWrapperContext() {
+	return {
+		wrapperRootClass: wrapperRootClassName(),
+		wrapperContainerHtml: (depth = 0) => renderWrapperContainer("html", depth),
+		wrapperContainerJsx: (depth = 0) => renderWrapperContainer("jsx", depth)
+	};
+}
+//#endregion
+export { base, blockCssdoc, createPreset, getWrapperContext, renderWrapperContainer, wrapperRootClassName };

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@pantoken/scaffold-base",
+  "version": "0.1.0",
+  "description": "Shared bingo-stratum Base for pantoken's scaffold presets: common options, the cssdoc.json block, and wrapper-layout markup context.",
+  "homepage": "https://pantoken.iywahl.com",
+  "bugs": "https://github.com/thedannywahl/pantoken/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thedannywahl/pantoken.git",
+    "directory": "packages/scaffold-base"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pantoken/plugin-layouts": "0.1.6",
+    "bingo-stratum": "^0.5.13",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^26.3.0",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
+    "vite-plus": "0.3.0"
+  },
+  "scripts": {
+    "generate": "node scripts/generate.ts",
+    "dev": "vp pack --watch",
+    "test": "vp run generate && vp test",
+    "check": "vp check"
+  }
+}