@thebase/ui 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project are documented in this file.
 
+## [v1.1.1] - 2026-10-04
+
+### Added
+- Analytics: `visitorContext()` export from `@thebase/ui/analytics` (and `window.thebase.analytics.visitorContext`). It returns the visitor's timezone (`tz`), browser language (`lang`) and a coarse screen bucket (`screen`: Mobile/Tablet/Laptop/Desktop). Pass it as `customProperties` to attach them to every event. Types are included as `BaseUIVisitorContext`. It's an additive export released as a patch by maintainer decision; nothing existing changed.
+- Docs: `docs/analytics.md` covers receiving events on your own backend (payload reference, Go Fiber v3 and FastAPI receivers), a "Sample dashboard" section, and "Visitor context". README has an Analytics section.
+- Examples: `examples/analytics/` contains a BaseUI analytics dashboard plus runnable Go Fiber and FastAPI sample backends (in-memory store, `GET /api/stats`, `DEMO_SEED=1` demo data). The landing page has an Analytics section, and the docs nav lists the Analytics guide.
+
+### Changed
+- Docs and examples: production pin examples now use `@1.1.1`.
+- `npm run dev` server: folder URLs serve their `index.html`, and `.go`/`.py`/`.mod` sources are served as text.
+
 ## [v1.1.0] - 2026-10-04
 
 ### Added

package/README.md

@@ -4,7 +4,7 @@ The Base UI is a CDN-installable UI kit built with Bootstrap 5 styling and Owl-e
 
 Its strong points: **no build step** — every component runs straight from a CDN `<script>`/import map, nothing to compile; **modular component design** — each component is a self-contained unit you import or mark up individually, not a monolith; **vanilla JavaScript/TypeScript** — no framework lock-in, no JSX, no compiler-specific syntax to learn; and this combination makes it well suited to building **WYSIWYG website builders**, where components must mount, unmount, and re-render dynamically from user-driven markup or drag-and-drop edits rather than a fixed build-time component tree.
 
-Both APIs load straight from a CDN — jsDelivr or unpkg — no build step, no self-hosting required. The snippets below use the `@latest` tag for readability; pin an exact version instead (e.g. `@1.1.0`, or `@1` to take only non-breaking updates) for any production page, since `@latest` can change what your page loads the moment a new version ships. Pure Owl usage:
+Both APIs load straight from a CDN — jsDelivr or unpkg — no build step, no self-hosting required. The snippets below use the `@latest` tag for readability; pin an exact version instead (e.g. `@1.1.1`, or `@1` to take only non-breaking updates) for any production page, since `@latest` can change what your page loads the moment a new version ships. Pure Owl usage:
 
 ```html
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.min.css">
@@ -56,9 +56,23 @@ For app-level theme controls, import `createThemeController`/`BaseUITheme` as `@
 
 Every component ships both APIs from `src/components/<name>/`: the static `b-ui` adapter (`<name>.js`, using `b-att-*` attributes and `baseui:*` events) and a pure Owl component class (`<name>.component.js`, exported from `@thebase/ui/components`). A few components' pure Owl treatment is intentionally lighter or reshaped versus their static markup-driven adapter — most notably `chart` (a slotted container; static Chart.js bootstrapping stays a `b-ui`-only concern) and the data-driven `data-table`/`combobox`/`command`/`calendar` (props-driven instead of slot/markup-driven). See each component's doc page under `docs/components/` for specifics.
 
+## Analytics
+
+BaseUI also ships an optional, cookieless web-analytics service (from 1.1.0). It is a standalone bundle — not part of `dist/baseui.min.js`/`baseui.esm.js`, with no Owl, Bootstrap, or component runtime dependency (~5.6 KB minified) — so you can load it with or without the rest of BaseUI. Nothing is collected until the page calls `init()`:
+
+```html
+<script type="module">
+  import { init, track } from "https://cdn.jsdelivr.net/npm/@thebase/ui@latest/dist/baseui.analytics.esm.js";
+  init({ backendUrl: "https://stats.example.com" }); // events POST to <backendUrl>/api/event
+  track("Signup", { props: { plan: "pro" } });
+</script>
+```
+
+From npm, use `import { init, track } from "@thebase/ui/analytics"`; for a classic `<script>` tag, `dist/baseui.analytics.min.js` sets `window.thebase.analytics`. It covers automatic and SPA pageviews, engagement (time on page and scroll depth), outbound links, file downloads, form submissions, and `thebase-event-*` class tagging. See [Analytics](docs/analytics.md) for every option, the payload format, opt-out, and sample Go Fiber / FastAPI backends. [`examples/analytics/`](examples/analytics/) holds a ready-to-run BaseUI dashboard for the collected data.
+
 ## Release notes
 
-See [CHANGELOG.md](CHANGELOG.md) for the full version history. Current version: **1.1.0**.
+See [CHANGELOG.md](CHANGELOG.md) for the full version history. Current version: **1.1.1**.
 
 ## Versioning policy
 
@@ -77,7 +91,7 @@ What each release type means:
 
 Anything prefixed `_`, undocumented internals, and the `docs/`/`examples/` sources are not part of the public API. Neither are the source-level authoring helpers described in [Component Authoring](docs/component-authoring.md) (`optional()`, `slotProps`, the `open-state.js` hooks, `bindBootstrapOverlay()`): they aren't exported from the package and may change in any release. Deprecated APIs keep working until the next major and are flagged in the CHANGELOG first.
 
-Pinning: use an exact version (`@1.1.0`) when you need byte-identical output, or the major range (`@1` on jsDelivr/unpkg, `^1.0.0` in npm) to receive fixes and features without breaking changes. Avoid `@latest` in production — it will move to the next major.
+Pinning: use an exact version (`@1.1.1`) when you need byte-identical output, or the major range (`@1` on jsDelivr/unpkg, `^1.0.0` in npm) to receive fixes and features without breaking changes. Avoid `@latest` in production — it will move to the next major.
 
 ## Project Documents
 
@@ -131,6 +145,6 @@ BaseUI includes the full Lucide SVG icon set as a built-in icon library. Use `<s
 
 ## Distribution
 
-The npm package publishes the built `dist/` artifacts plus package metadata. The browser build bundles Bootstrap CSS, and `dist/baseui.min.js`/`baseui.esm.js` embed Bootstrap's JS bundle, the Owl runtime, every pure Owl component class, and the theme helper directly (Bootstrap then Owl then BaseUI, in that load order) — consumers install BaseUI with one stylesheet and one script tag for either API. Bootstrap's JS drives every component that has a Bootstrap JS equivalent (modal, dropdown, collapse, tab, toast, carousel, tooltip, popover, alert); BaseUI's `.behavior.js`/`runtime/*.js` helpers wrap Bootstrap's JS API instead of reimplementing it, for both the static and pure-Owl APIs. `dist/bootstrap.bundle.min.js` also ships standalone (unmodified) and `dist/baseui.icons.esm.js` stays a separate, deliberate exception (2000+ generated icon components would blow the main bundle's size budget) — everything else is one file. Every shipped CSS/JS artifact is minified — there are no unminified twins to keep in sync.
+The npm package publishes the built `dist/` artifacts plus package metadata. The browser build bundles Bootstrap CSS, and `dist/baseui.min.js`/`baseui.esm.js` embed Bootstrap's JS bundle, the Owl runtime, every pure Owl component class, and the theme helper directly (Bootstrap then Owl then BaseUI, in that load order) — consumers install BaseUI with one stylesheet and one script tag for either API. Bootstrap's JS drives every component that has a Bootstrap JS equivalent (modal, dropdown, collapse, tab, toast, carousel, tooltip, popover, alert); BaseUI's `.behavior.js`/`runtime/*.js` helpers wrap Bootstrap's JS API instead of reimplementing it, for both the static and pure-Owl APIs. `dist/bootstrap.bundle.min.js` also ships standalone (unmodified) and `dist/baseui.icons.esm.js` stays a separate, deliberate exception (2000+ generated icon components would blow the main bundle's size budget), as does the opt-in analytics service (`dist/baseui.analytics.esm.js`/`.min.js`, so pages that don't track pay nothing for it) — everything else is one file. Every shipped CSS/JS artifact is minified — there are no unminified twins to keep in sync.
 
 The published tarball also carries `docs/*.md` and `docs/components/` (see the "Project Documents" section above), `README.md`, `CHANGELOG.md`, and `LICENSE` — `docs/v2/` and `docs/component-authoring.md` are deliberately excluded from `package.json`'s `files` list since they're development-time-only references for working inside this repo.

package/bin/create-baseui-app.mjs

@@ -2,6 +2,7 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 
 const ownPackageJson = JSON.parse(
   readFileSync(new URL("../package.json", import.meta.url), "utf8"),
@@ -16,13 +17,18 @@ function toPackageName(name) {
     .replace(/^-+|-+$/g, "") || "baseui-app";
 }
 
-/** Builds the fixed set of Vite + BaseUI scaffold files for a project named `appName`. */
-function buildTemplateFiles(appName, baseuiVersion) {
-  const title = appName
+/** Turns a kebab/snake-case app name into a human-readable title, e.g. "qr-page" -> "Qr Page". */
+function toTitle(appName) {
+  return appName
     .split(/[-_]/)
     .filter(Boolean)
     .map((word) => word[0].toUpperCase() + word.slice(1))
     .join(" ");
+}
+
+/** Builds the fixed set of Vite + BaseUI scaffold files for a project named `appName`. */
+function buildTemplateFiles(appName, baseuiVersion) {
+  const title = toTitle(appName);
 
   return {
     "package.json": JSON.stringify(
@@ -140,6 +146,375 @@ npm run dev
   };
 }
 
+/** Builds one page's HTML shell: mounts #app and loads that page's own entry script. */
+function pageHtml(title, entryScript) {
+  return `<!doctype html>
+<html lang="en" b-theme="light">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${title}</title>
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+  </head>
+  <body class="bg-body text-body">
+    <div id="app"></div>
+    <script type="module" src="${entryScript}"></script>
+  </body>
+</html>
+`;
+}
+
+/** Builds one page's entry script: loads its templates/component and mounts via the shared mountPage helper. */
+function pageMain(componentName, templatesImportPath, componentImportPath) {
+  return `import "@thebase/ui/baseui.css";
+import pageTemplates from "${templatesImportPath}?raw";
+import { ${componentName} } from "${componentImportPath}";
+import { mountPage } from "../mount-page.js";
+import "../style.css";
+
+await mountPage(${componentName}, pageTemplates);
+`;
+}
+
+/** Builds a 4-page Vite + BaseUI starter (landing, login, signup, an authenticated home shell) for a
+ * project named `appName` — each page is its own Owl root mounted by its own HTML entry, composed
+ * from the same blocks as `examples/blocks/login-03.html`, `signup-03.html` and `sidebar-02.html`. */
+function buildStarterFiles(appName, baseuiVersion) {
+  const title = toTitle(appName);
+
+  return {
+    "package.json": JSON.stringify(
+      {
+        name: appName,
+        private: true,
+        version: "0.0.1",
+        type: "module",
+        scripts: {
+          dev: "vite",
+          build: "vite build",
+          preview: "vite preview",
+        },
+        dependencies: {
+          "@thebase/ui": `^${baseuiVersion}`,
+        },
+        devDependencies: {
+          vite: "^8.2.1",
+        },
+      },
+      null,
+      2,
+    ) + "\n",
+
+    "vite.config.js": `import { defineConfig } from "vite";
+import { fileURLToPath } from "node:url";
+
+/** Resolves a file in this config's own directory, Node-ESM-safe (no __dirname in ESM). */
+const here = (file) => fileURLToPath(new URL(file, import.meta.url));
+
+export default defineConfig({
+  server: { open: true },
+  build: {
+    rollupOptions: {
+      input: {
+        main: here("./index.html"),
+        login: here("./login.html"),
+        signup: here("./signup.html"),
+        home: here("./home.html"),
+      },
+    },
+  },
+});
+`,
+
+    ".gitignore": `node_modules/\ndist/\n`,
+
+    "public/favicon.svg": `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"
+  fill="none" stroke="#ffffff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <rect width="24" height="24" rx="5" fill="#0f172a" stroke="none" />
+  <path d="M8 12h8" />
+  <path d="M12 8v8" />
+</svg>
+`,
+
+    "src/style.css": `/* App-specific styles layered on top of @thebase/ui/baseui.css go here. */\n`,
+
+    "src/mount-page.js": `import { mount } from "@thebase/ui";
+import baseuiTemplates from "@thebase/ui/dist/baseui.templates.xml?raw";
+
+/** Both files are full <templates>...</templates> documents; strip each one's outer wrapper before
+ * joining them, otherwise the merged string has two root elements and Owl's XML parser throws. */
+const stripTemplatesWrapper = (xml) =>
+  xml.replace(/^\\s*<templates[^>]*>/, "").replace(/<\\/templates>\\s*$/, "");
+
+/** Merges BaseUI's component templates with one page's own templates and mounts its root component. */
+export async function mountPage(Root, pageTemplatesXml) {
+  const templates = \`<templates>\${stripTemplatesWrapper(baseuiTemplates)}\${stripTemplatesWrapper(pageTemplatesXml)}</templates>\`;
+  await mount(Root, document.getElementById("app"), { templates });
+}
+`,
+
+    "index.html": pageHtml(title, "/src/landing/main.js"),
+    "src/landing/main.js": pageMain("Landing", "./Landing.xml", "./Landing.js"),
+    "src/landing/Landing.js": `import { Component } from "@thebase/ui";
+import { Button, Card, CardBody, CardHeader, CardTitle, Icon } from "@thebase/ui";
+
+/** Marketing landing page: header with a login link, hero pitch, feature grid, footer. */
+export class Landing extends Component {
+  static template = "app.Landing";
+  static components = { Button, Card, CardBody, CardHeader, CardTitle, Icon };
+}
+`,
+    "src/landing/Landing.xml": `<templates xml:space="preserve">
+  <t t-name="app.Landing">
+    <div class="d-flex flex-column min-vh-100">
+      <header class="border-bottom">
+        <div class="container d-flex align-items-center justify-content-between py-3">
+          <a href="/" class="d-inline-flex align-items-center gap-2 fw-medium text-decoration-none">
+            <Icon name="'gallery-vertical-end'"/>
+            ${title}
+          </a>
+          <Button variant="'outline'" onClick="() => window.location.assign('/login.html')">Login</Button>
+        </div>
+      </header>
+
+      <section class="container py-5 text-center">
+        <h1 class="display-5 fw-bold mb-3">Build faster with ${title}</h1>
+        <p class="lead text-muted mx-auto mb-4" style="max-width: 40rem">
+          A starter scaffold wired up with BaseUI — pure Owl components, Bootstrap styling, and the pages you need to ship day one.
+        </p>
+        <div class="d-flex justify-content-center gap-3">
+          <Button icon="'rocket'" onClick="() => window.location.assign('/signup.html')">Get started</Button>
+          <Button variant="'outline'" onClick="() => window.location.assign('/login.html')">Login</Button>
+        </div>
+      </section>
+
+      <section class="container py-5">
+        <div class="row g-4">
+          <div class="col-12 col-md-4">
+            <Card className="'h-100'">
+              <CardHeader className="'d-flex align-items-center gap-2'"><Icon name="'zap'"/><CardTitle>Fast by default</CardTitle></CardHeader>
+              <CardBody>Vite dev server and production build, pre-wired to BaseUI's CDN or local dist.</CardBody>
+            </Card>
+          </div>
+          <div class="col-12 col-md-4">
+            <Card className="'h-100'">
+              <CardHeader className="'d-flex align-items-center gap-2'"><Icon name="'layout-dashboard'"/><CardTitle>Pages included</CardTitle></CardHeader>
+              <CardBody>Landing, login, signup and an authenticated home shell, ready to extend.</CardBody>
+            </Card>
+          </div>
+          <div class="col-12 col-md-4">
+            <Card className="'h-100'">
+              <CardHeader className="'d-flex align-items-center gap-2'"><Icon name="'component'"/><CardTitle>Pure Owl components</CardTitle></CardHeader>
+              <CardBody>Every page composes real BaseUI components — swap or extend without fighting the markup.</CardBody>
+            </Card>
+          </div>
+        </div>
+      </section>
+
+      <footer class="border-top mt-auto">
+        <div class="container py-4 d-flex align-items-center justify-content-between">
+          <small class="text-muted">© ${title}. All rights reserved.</small>
+          <a href="/login.html" class="small text-decoration-underline">Login</a>
+        </div>
+      </footer>
+    </div>
+  </t>
+</templates>
+`,
+
+    "login.html": pageHtml(`Login — ${title}`, "/src/login/main.js"),
+    "src/login/main.js": pageMain("Login", "./Login.xml", "./Login.js"),
+    "src/login/Login.js": `import { Component } from "@thebase/ui";
+import { Button, Card, CardBody, Field, FieldGroup, Icon, Input, Label } from "@thebase/ui";
+
+/** Login page (ported from examples/blocks/login-03.html): email/password card, redirects home on submit. */
+export class Login extends Component {
+  static template = "app.Login";
+  static components = { Button, Card, CardBody, Field, FieldGroup, Icon, Input, Label };
+}
+`,
+    "src/login/Login.xml": `<templates xml:space="preserve">
+  <t t-name="app.Login">
+    <div class="d-flex flex-column align-items-center justify-content-center gap-4 min-vh-100 bg-body-tertiary p-4">
+      <div class="d-flex flex-column align-items-center gap-4 col-12 col-sm-8 col-md-6 col-lg-4">
+        <a href="/" class="d-inline-flex align-items-center gap-2 fw-medium text-decoration-none">
+          <Icon name="'gallery-vertical-end'"/>
+          ${title}
+        </a>
+        <Card className="'w-100'">
+          <CardBody>
+            <form class="d-flex flex-column gap-4">
+              <div class="d-flex flex-column gap-2 text-center">
+                <h2 class="h4 mb-0">Login to your account</h2>
+                <p class="text-muted mb-0">Enter your email below to login to your account</p>
+              </div>
+              <FieldGroup>
+                <Field>
+                  <Label>Email</Label>
+                  <Input type="'email'" placeholder="'m@example.com'"/>
+                </Field>
+                <Field>
+                  <div class="d-flex align-items-center justify-content-between">
+                    <Label>Password</Label>
+                    <a href="#" class="small text-decoration-underline">Forgot your password?</a>
+                  </div>
+                  <Input type="'password'"/>
+                </Field>
+                <Button icon="'log-in'" onClick="() => window.location.assign('/home.html')">Login</Button>
+                <Button variant="'outline'" icon="'mail'">Login with email</Button>
+              </FieldGroup>
+              <p class="text-center small mb-0">Don&apos;t have an account? <a href="/signup.html" class="text-decoration-underline">Sign up</a></p>
+            </form>
+          </CardBody>
+        </Card>
+      </div>
+    </div>
+  </t>
+</templates>
+`,
+
+    "signup.html": pageHtml(`Sign up — ${title}`, "/src/signup/main.js"),
+    "src/signup/main.js": pageMain("Signup", "./Signup.xml", "./Signup.js"),
+    "src/signup/Signup.js": `import { Component } from "@thebase/ui";
+import { Button, Card, CardBody, Field, FieldGroup, Icon, Input, Label } from "@thebase/ui";
+
+/** Signup page (ported from examples/blocks/signup-03.html): single email field, sends the user to login after submit. */
+export class Signup extends Component {
+  static template = "app.Signup";
+  static components = { Button, Card, CardBody, Field, FieldGroup, Icon, Input, Label };
+}
+`,
+    "src/signup/Signup.xml": `<templates xml:space="preserve">
+  <t t-name="app.Signup">
+    <div class="d-flex flex-column align-items-center justify-content-center gap-4 min-vh-100 bg-body-tertiary p-4">
+      <div class="d-flex flex-column align-items-center gap-4 col-12 col-sm-8 col-md-6 col-lg-4">
+        <a href="/" class="d-inline-flex align-items-center gap-2 fw-medium text-decoration-none">
+          <Icon name="'gallery-vertical-end'"/>
+          ${title}
+        </a>
+        <Card className="'w-100'">
+          <CardBody>
+            <form class="d-flex flex-column gap-4">
+              <div class="d-flex flex-column gap-2 text-center">
+                <h2 class="h4 mb-0">Create an account</h2>
+                <p class="text-muted mb-0">Enter your email below to create your account</p>
+              </div>
+              <FieldGroup>
+                <Field>
+                  <Label>Email</Label>
+                  <Input type="'email'" placeholder="'m@example.com'"/>
+                </Field>
+                <Button icon="'user-plus'" onClick="() => window.location.assign('/login.html')">Sign up</Button>
+                <Button variant="'outline'" icon="'mail'">Sign up with email</Button>
+              </FieldGroup>
+              <p class="text-center small mb-0">Already have an account? <a href="/login.html" class="text-decoration-underline">Login</a></p>
+            </form>
+          </CardBody>
+        </Card>
+      </div>
+    </div>
+  </t>
+</templates>
+`,
+
+    "home.html": pageHtml(`Home — ${title}`, "/src/home/main.js"),
+    "src/home/main.js": pageMain("Home", "./Home.xml", "./Home.js"),
+    "src/home/Home.js": `import { Component, useState } from "@thebase/ui";
+import {
+  Breadcrumb, BreadcrumbItem, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator,
+  Button, Icon, InputGroup, InputGroupAddon, InputGroupInput, Separator,
+  Shell, ShellContent, ShellHeader, ShellMain, ShellNav, ShellSidebar, ShellSidebarHeader,
+  SidebarGroupCollapsible, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarTrigger,
+} from "@thebase/ui";
+
+/** Authenticated home shell (ported from examples/blocks/sidebar-02.html): collapsible sidebar nav
+ * + sticky header, reached after login/signup; owns the sidebar's collapsed/expanded state. */
+export class Home extends Component {
+  static template = "app.Home";
+  static components = {
+    Breadcrumb, BreadcrumbItem, BreadcrumbList, BreadcrumbPage, BreadcrumbSeparator,
+    Button, Icon, InputGroup, InputGroupAddon, InputGroupInput, Separator,
+    Shell, ShellContent, ShellHeader, ShellMain, ShellNav, ShellSidebar, ShellSidebarHeader,
+    SidebarGroupCollapsible, SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarTrigger,
+  };
+
+  setup() {
+    this.state = useState({ collapsed: false });
+  }
+}
+`,
+    "src/home/Home.xml": `<templates xml:space="preserve">
+  <t t-name="app.Home">
+    <Shell className="'border'" collapsed="state.collapsed" onCollapsedChange="(value) => { state.collapsed = value; }">
+      <ShellSidebar>
+        <ShellSidebarHeader>
+          <a href="/" class="d-flex align-items-center gap-2 text-decoration-none fw-medium">
+            <Icon name="'gallery-vertical-end'"/>
+            <span class="d-flex flex-column lh-sm">
+              <span>${title}</span>
+              <small class="text-body-secondary fw-normal">Dashboard</small>
+            </span>
+          </a>
+        </ShellSidebarHeader>
+        <InputGroup>
+          <InputGroupAddon><Icon name="'search'"/></InputGroupAddon>
+          <InputGroupInput type="'search'" placeholder="'Search...'"/>
+        </InputGroup>
+        <ShellNav className="'d-flex flex-column gap-2'">
+          <SidebarGroupCollapsible label="'Getting Started'" defaultOpen="true">
+            <SidebarMenu>
+              <SidebarMenuItem><SidebarMenuButton href="'#'" icon="'layout-dashboard'" active="true">Overview</SidebarMenuButton></SidebarMenuItem>
+              <SidebarMenuItem><SidebarMenuButton href="'#'" icon="'users'">Customers</SidebarMenuButton></SidebarMenuItem>
+              <SidebarMenuItem><SidebarMenuButton href="'#'" icon="'settings'">Settings</SidebarMenuButton></SidebarMenuItem>
+            </SidebarMenu>
+          </SidebarGroupCollapsible>
+        </ShellNav>
+      </ShellSidebar>
+      <ShellMain>
+        <ShellHeader className="'border-bottom p-3'">
+          <SidebarTrigger/>
+          <Separator orientation="'vertical'"/>
+          <Breadcrumb>
+            <BreadcrumbList>
+              <BreadcrumbItem><BreadcrumbPage>Overview</BreadcrumbPage></BreadcrumbItem>
+            </BreadcrumbList>
+          </Breadcrumb>
+          <Button variant="'outline'" size="'sm'" className="'ms-auto'" icon="'log-out'" onClick="() => window.location.assign('/index.html')">Logout</Button>
+        </ShellHeader>
+        <ShellContent className="'d-flex flex-column gap-3'">
+          <div class="row row-cols-3 g-3">
+            <div class="col"><div class="ratio ratio-16x9 bg-body-secondary rounded-4"></div></div>
+            <div class="col"><div class="ratio ratio-16x9 bg-body-secondary rounded-4"></div></div>
+            <div class="col"><div class="ratio ratio-16x9 bg-body-secondary rounded-4"></div></div>
+          </div>
+          <div class="flex-grow-1 bg-body-secondary rounded-4"></div>
+        </ShellContent>
+      </ShellMain>
+    </Shell>
+  </t>
+</templates>
+`,
+
+    "README.md": `# ${title}
+
+Scaffolded with \`@thebase/ui\`'s CLI (\`create-baseui-app init\`): Vite + BaseUI, pure Owl API, 4 pages.
+
+- \`/\` — landing page (header, hero, features, footer)
+- \`/login.html\` — login (redirects to \`/home.html\` on submit)
+- \`/signup.html\` — signup (redirects to \`/login.html\` on submit)
+- \`/home.html\` — authenticated home shell (sidebar + header, logout returns to \`/\`)
+
+None of the pages call a real backend yet — wire up \`Login\`/\`Signup\`'s button \`onClick\` handlers to
+your own auth API once you have one.
+
+\`\`\`sh
+npm install
+npm run dev
+\`\`\`
+`,
+  };
+}
+
 /** Writes each template file under targetDir, skipping any that already exist (convert mode is additive/non-destructive). */
 function writeFiles(targetDir, files, { overwrite }) {
   const written = [];
@@ -173,6 +548,7 @@ function parseFlags(argv) {
     if (arg === "--no-install") flags.install = false;
     else if (arg === "--force") flags.force = true;
     else if (arg === "--version") flags.version = argv[++i];
+    else if (arg === "--config") flags.config = argv[++i];
     else positional.push(arg);
   }
   return { flags, positional };
@@ -205,6 +581,37 @@ function cmdCreate(argv) {
   console.log(`\nNext steps:\n  cd ${rawName}${flags.install ? "" : "\n  npm install"}\n  npm run dev`);
 }
 
+/** Scaffolds the 4-page starter (landing/login/signup/home) in a new ./<app-name> folder. */
+function cmdInit(argv) {
+  const { flags, positional } = parseFlags(argv);
+  const rawName = positional[0];
+  if (!rawName) {
+    console.error("Usage: create-baseui-app init <app-name> [--version <x.y.z>] [--no-install] [--force]");
+    process.exit(1);
+  }
+  const appName = toPackageName(rawName);
+  const targetDir = path.resolve(process.cwd(), rawName);
+
+  if (existsSync(targetDir) && readdirSync(targetDir).length > 0 && !flags.force) {
+    console.error(`Directory "${rawName}" already exists and is not empty. Use --force to write into it anyway.`);
+    process.exit(1);
+  }
+
+  const baseuiVersion = flags.version || ownPackageJson.version;
+  const files = buildStarterFiles(appName, baseuiVersion);
+  const { written } = writeFiles(targetDir, files, { overwrite: flags.force ?? false });
+
+  console.log(`Scaffolded a 4-page Vite + BaseUI starter in ${targetDir}`);
+  written.forEach((f) => console.log(`  create ${f}`));
+
+  if (flags.install) runInstall(targetDir);
+
+  console.log(
+    `\nNext steps:\n  cd ${rawName}${flags.install ? "" : "\n  npm install"}\n  npm run dev` +
+      `\n\nPages: / (landing), /login.html, /signup.html, /home.html`,
+  );
+}
+
 function cmdConvert(argv) {
   const { flags, positional } = parseFlags(argv);
   const targetDir = path.resolve(process.cwd(), positional[0] || ".");
@@ -248,6 +655,34 @@ function cmdConvert(argv) {
   console.log(`\nNext steps:\n  npm run dev`);
 }
 
+/** Generates manifest.webmanifest + sw.js for a PWA from a `baseui.pwa.config.js` the user wrote,
+ * using @thebase/ui's buildManifest/buildServiceWorker (see docs/usage-guide.md "PWA toolkit"). */
+async function cmdPwa(argv) {
+  const { flags, positional } = parseFlags(argv);
+  const targetDir = path.resolve(process.cwd(), positional[0] || ".");
+  const configPath = path.resolve(targetDir, flags.config || "baseui.pwa.config.js");
+
+  if (!existsSync(configPath)) {
+    console.error(
+      `Config file not found: ${configPath}\n` +
+        "Create it first — export default { manifest: {...}, serviceWorker: {...} }, " +
+        "see docs/usage-guide.md \"PWA toolkit\" for the full config shape.",
+    );
+    process.exit(1);
+  }
+
+  const { manifest, serviceWorker } = (await import(pathToFileURL(configPath).href)).default;
+  const { buildManifest, buildServiceWorker } = await import("../dist/baseui.pwa.esm.js");
+
+  writeFileSync(
+    path.join(targetDir, "manifest.webmanifest"),
+    JSON.stringify(buildManifest(manifest), null, 2) + "\n",
+  );
+  writeFileSync(path.join(targetDir, "sw.js"), buildServiceWorker(serviceWorker));
+
+  console.log(`Wrote manifest.webmanifest and sw.js in ${targetDir}`);
+}
+
 function printHelp() {
   console.log(`@thebase/ui project CLI
 
@@ -258,6 +693,16 @@ Usage:
   create-baseui-app convert [path] [--version <x.y.z>] [--no-install]
       Turn an existing (non-npm) folder into a Vite + BaseUI project, in place.
       Never overwrites files that already exist; only fills in what's missing.
+
+  create-baseui-app init <app-name> [--version <x.y.z>] [--no-install] [--force]
+      Scaffold a ready-to-start 4-page project in ./<app-name>: a landing page
+      (header/hero/features/footer), login, signup, and an authenticated home
+      shell (sidebar + header) — ported from the login-03/signup-03/sidebar-02
+      example blocks.
+
+  create-baseui-app pwa [path] [--config <file>]
+      Generate manifest.webmanifest + sw.js in [path] (default ".") from a
+      baseui.pwa.config.js config file (default name, override with --config).
 `);
 }
 
@@ -265,4 +710,6 @@ const [, , command, ...rest] = process.argv;
 
 if (command === "create") cmdCreate(rest);
 else if (command === "convert") cmdConvert(rest);
+else if (command === "init") cmdInit(rest);
+else if (command === "pwa") await cmdPwa(rest);
 else printHelp();

package/dist/baseui.analytics.esm.js

@@ -1 +1 @@
-var H=["pdf","xlsx","docx","txt","rtf","csv","exe","key","pps","ppt","pptx","7z","pkg","rar","gz","zip","avi","mov","mp4","mpeg","wmv","midi","mp3","wav","wma","dmg"];var U=/^localhost$|^127(\.[0-9]+){0,2}\.[0-9]+$|^\[::1?\]$/,F=/thebase-event-name(=|--)(.+)/,B="/api/event",$=/^(https?:\/\/|\/)/,o={},P=H,p,A,w=!1,v,C,O={},E=-1,r=0,l=0,u,s;function z(e){if(o.isInitialized)throw Error("thebase.analytics.init() can only be called once");let t=e.apiPath||B,i=e.endpoint||e.backendUrl&&`${e.backendUrl.replace(/\/+$/,"")}/${t.replace(/^\/+/,"")}`;if(!i)throw Error("thebase.analytics.init(): backendUrl (or endpoint) is required");if(!$.test(i))throw Error(`thebase.analytics.init(): "${i}" must be an http(s):// URL or a /path on this site`);Object.assign(o,e,{domain:e.domain||location.hostname,endpoint:i,autoCapturePageviews:e.autoCapturePageviews!==!1,logging:e.logging!==!1,bindToWindow:e.bindToWindow!==!1,isInitialized:!0})}function I(e,t,i){fetch(e,{method:"POST",headers:{"Content-Type":"text/plain"},keepalive:!0,body:JSON.stringify(t)}).then(n=>i?.callback?.({status:n.status})).catch(n=>i?.callback?.({error:n}))}function V(){w&&(N(),u=S(),s=L())}function q(e){v=!1,C=e.u,O=e.p,E=-1,l=0,r=Date.now(),G()}function N(){let e=M();if(v||E>=s&&e<3e3)return;E=s;let t={n:"engagement",sd:Math.round(s/u*100),d:o.domain,u:C,p:O,e,v:36};r=0,l=0,o.hashBasedRouting&&(t.h=1),I(o.endpoint,t)}function m(){document.visibilityState==="visible"&&document.hasFocus()&&r===0?r=Date.now():(document.visibilityState==="hidden"||!document.hasFocus())&&(l=M(),r=0,N())}function G(){w||(document.addEventListener("visibilitychange",m),window.addEventListener("blur",m),window.addEventListener("focus",m),w=!0)}function M(){return r?l+(Date.now()-r):l}function S(){let e=document.body,t=document.documentElement;return Math.max(e.scrollHeight,e.offsetHeight,e.clientHeight,t.scrollHeight,t.offsetHeight,t.clientHeight)}function L(){return u<=window.innerHeight?u:window.scrollY+window.innerHeight}function K(){u=S()}function W(){s=Math.max(s,L())}function j(){u=S(),s=L(),new window.ResizeObserver(K).observe(document.documentElement),document.addEventListener("scroll",W)}function g(e,t){if(!o.isInitialized)throw Error("thebase.analytics.track() can only be called after thebase.analytics.init()");let i=e==="pageview";if(i&&V(),!o.captureOnLocalhost){if(U.test(location.hostname)||location.protocol==="file:")return d(e,t,"localhost");if((window._phantom||window.__nightmare||navigator.webdriver||window.Cypress)&&!window.__thebase)return d(e,t)}try{if(localStorage.thebase_ignore==="true")return d(e,t,"localStorage flag")}catch{}let n={n:e,v:36,u:t?.u||t?.url||location.href,d:o.domain,r:document.referrer||null};if(t?.props&&(n.p=t.props),t?.interactive===!1&&(n.i=!1),t?.revenue&&(n.$=t.revenue),o.customProperties){let a=typeof o.customProperties=="function"?o.customProperties(e):o.customProperties;typeof a=="object"&&(n.p={...a,...n.p})}if(o.hashBasedRouting&&(n.h=1),typeof o.transformRequest=="function"&&(n=o.transformRequest(n),!n))return d(e,t,"transformRequest");i&&q(n),I(o.endpoint,n,t)}function d(e,t,i){i&&o.logging&&console.warn(`Ignoring Event: ${i}`),t?.callback?.(),e==="pageview"&&(v=!0)}function x(e){return e?.tagName?.toLowerCase()==="a"}function Y(e){for(;e&&(e.tagName===void 0||!x(e)||!e.href);)e=e.parentNode;return e}function J(e){return e&&typeof e.href=="string"&&e.host&&e.host!==location.host}function Q(e){return!!e&&P.includes(e.split(".").pop())}function T(e){return!!e?.classList&&[...e.classList].some(t=>F.test(t))}function y(e,t){return!!e&&t<=3&&(T(e)||y(e.parentNode,t+1))}function D(e){let t=T(e)?e:e?.parentNode,i={name:null,props:{},revenue:{}};if(!t?.classList)return i;for(let n of t.classList){let a=n.match(/thebase-event-(.+)(=|--)(.+)/);if(a){let _=a[3].replace(/\+/g," ");a[1].toLowerCase()==="name"?i.name=_:i.props[a[1]]=_}let c=n.match(/thebase-revenue-(.+)(=|--)(.+)/);c&&(i.revenue[c[1]]=c[3])}return i}function f(e){g(e.name,{props:e.props,revenue:e.revenue})}function k(e){if(e.type==="auxclick"&&e.button!==1)return;let t=Y(e.target);if(y(t,0))return;if(o.outboundLinks&&J(t))return f({name:"Outbound Link: Click",props:{url:t.href}});let i=t&&typeof t.href=="string"&&t.href.split("?")[0];o.fileDownloads&&Q(i)&&f({name:"File Download",props:{url:i}})}function R(e){if(e.type==="auxclick"&&e.button!==1)return;let t,i,n=e.target;for(let c=0;c<=3&&n;c++){if(n.tagName?.toLowerCase()==="form")return;x(n)&&(t=n),T(n)&&(i=n),n=n.parentNode}if(!i)return;let a=D(i);t&&(a.props.url=t.href),f(a)}function X(e){let t=e.target;(t.hasAttribute("novalidate")||t.checkValidity())&&!y(t,0)&&g("Form: Submission")}function Z(e){let t=D(e.target);t.name&&f(t)}function ee(){document.addEventListener("click",k),document.addEventListener("auxclick",k),Array.isArray(o.fileDownloads?.fileExtensions)&&(P=o.fileDownloads.fileExtensions),o.formSubmissions&&document.addEventListener("submit",X,!0),document.addEventListener("submit",Z),document.addEventListener("click",R),document.addEventListener("auxclick",R)}function h(e){!o.hashBasedRouting&&e&&p===location.pathname||(p=location.pathname,g("pageview"))}function b(){h(!0)}function te(...e){A.apply(this,e),b()}function ne(){!p&&document.visibilityState==="visible"&&h()}function ie(e){e.persisted&&h()}function oe(){o.hashBasedRouting?window.addEventListener("hashchange",b):(A=window.history.pushState,window.history.pushState=te,window.addEventListener("popstate",b)),document.visibilityState==="hidden"||document.visibilityState==="prerender"?document.addEventListener("visibilitychange",ne):h(),window.addEventListener("pageshow",ie)}function ae(e){z(e||{}),j(),o.autoCapturePageviews&&oe(),ee(),o.bindToWindow&&(window.thebase??(window.thebase={}),window.thebase.track=g,window.thebase.track.s="npm",window.thebase.track.v=36,window.thebase.track.l=!0)}export{H as DEFAULT_FILE_TYPES,ae as init,g as track};
+var H=["pdf","xlsx","docx","txt","rtf","csv","exe","key","pps","ppt","pptx","7z","pkg","rar","gz","zip","avi","mov","mp4","mpeg","wmv","midi","mp3","wav","wma","dmg"];var U=/^localhost$|^127(\.[0-9]+){0,2}\.[0-9]+$|^\[::1?\]$/,F=/thebase-event-name(=|--)(.+)/,B="/api/event",z=/^(https?:\/\/|\/)/,o={},P=H,m,C,w=!1,v,O,A={},E=-1,r=0,l=0,u,s;function $(e){if(o.isInitialized)throw Error("thebase.analytics.init() can only be called once");let t=e.apiPath||B,i=e.endpoint||e.backendUrl&&`${e.backendUrl.replace(/\/+$/,"")}/${t.replace(/^\/+/,"")}`;if(!i)throw Error("thebase.analytics.init(): backendUrl (or endpoint) is required");if(!z.test(i))throw Error(`thebase.analytics.init(): "${i}" must be an http(s):// URL or a /path on this site`);Object.assign(o,e,{domain:e.domain||location.hostname,endpoint:i,autoCapturePageviews:e.autoCapturePageviews!==!1,logging:e.logging!==!1,bindToWindow:e.bindToWindow!==!1,isInitialized:!0})}function I(e,t,i){fetch(e,{method:"POST",headers:{"Content-Type":"text/plain"},keepalive:!0,body:JSON.stringify(t)}).then(n=>i?.callback?.({status:n.status})).catch(n=>i?.callback?.({error:n}))}function V(){w&&(M(),u=S(),s=L())}function q(e){v=!1,O=e.u,A=e.p,E=-1,l=0,r=Date.now(),G()}function M(){let e=N();if(v||E>=s&&e<3e3)return;E=s;let t={n:"engagement",sd:Math.round(s/u*100),d:o.domain,u:O,p:A,e,v:36};r=0,l=0,o.hashBasedRouting&&(t.h=1),I(o.endpoint,t)}function p(){document.visibilityState==="visible"&&document.hasFocus()&&r===0?r=Date.now():(document.visibilityState==="hidden"||!document.hasFocus())&&(l=N(),r=0,M())}function G(){w||(document.addEventListener("visibilitychange",p),window.addEventListener("blur",p),window.addEventListener("focus",p),w=!0)}function N(){return r?l+(Date.now()-r):l}function S(){let e=document.body,t=document.documentElement;return Math.max(e.scrollHeight,e.offsetHeight,e.clientHeight,t.scrollHeight,t.offsetHeight,t.clientHeight)}function L(){return u<=window.innerHeight?u:window.scrollY+window.innerHeight}function K(){u=S()}function W(){s=Math.max(s,L())}function j(){u=S(),s=L(),new window.ResizeObserver(K).observe(document.documentElement),document.addEventListener("scroll",W)}function ae(){let e=window.innerWidth;return{tz:Intl.DateTimeFormat().resolvedOptions().timeZone,lang:navigator.language,screen:e<576?"Mobile":e<992?"Tablet":e<1440?"Laptop":"Desktop"}}function g(e,t){if(!o.isInitialized)throw Error("thebase.analytics.track() can only be called after thebase.analytics.init()");let i=e==="pageview";if(i&&V(),!o.captureOnLocalhost){if(U.test(location.hostname)||location.protocol==="file:")return d(e,t,"localhost");if((window._phantom||window.__nightmare||navigator.webdriver||window.Cypress)&&!window.__thebase)return d(e,t)}try{if(localStorage.thebase_ignore==="true")return d(e,t,"localStorage flag")}catch{}let n={n:e,v:36,u:t?.u||t?.url||location.href,d:o.domain,r:document.referrer||null};if(t?.props&&(n.p=t.props),t?.interactive===!1&&(n.i=!1),t?.revenue&&(n.$=t.revenue),o.customProperties){let a=typeof o.customProperties=="function"?o.customProperties(e):o.customProperties;typeof a=="object"&&(n.p={...a,...n.p})}if(o.hashBasedRouting&&(n.h=1),typeof o.transformRequest=="function"&&(n=o.transformRequest(n),!n))return d(e,t,"transformRequest");i&&q(n),I(o.endpoint,n,t)}function d(e,t,i){i&&o.logging&&console.warn(`Ignoring Event: ${i}`),t?.callback?.(),e==="pageview"&&(v=!0)}function x(e){return e?.tagName?.toLowerCase()==="a"}function Y(e){for(;e&&(e.tagName===void 0||!x(e)||!e.href);)e=e.parentNode;return e}function J(e){return e&&typeof e.href=="string"&&e.host&&e.host!==location.host}function Z(e){return!!e&&P.includes(e.split(".").pop())}function T(e){return!!e?.classList&&[...e.classList].some(t=>F.test(t))}function y(e,t){return!!e&&t<=3&&(T(e)||y(e.parentNode,t+1))}function D(e){let t=T(e)?e:e?.parentNode,i={name:null,props:{},revenue:{}};if(!t?.classList)return i;for(let n of t.classList){let a=n.match(/thebase-event-(.+)(=|--)(.+)/);if(a){let k=a[3].replace(/\+/g," ");a[1].toLowerCase()==="name"?i.name=k:i.props[a[1]]=k}let c=n.match(/thebase-revenue-(.+)(=|--)(.+)/);c&&(i.revenue[c[1]]=c[3])}return i}function f(e){g(e.name,{props:e.props,revenue:e.revenue})}function _(e){if(e.type==="auxclick"&&e.button!==1)return;let t=Y(e.target);if(y(t,0))return;if(o.outboundLinks&&J(t))return f({name:"Outbound Link: Click",props:{url:t.href}});let i=t&&typeof t.href=="string"&&t.href.split("?")[0];o.fileDownloads&&Z(i)&&f({name:"File Download",props:{url:i}})}function R(e){if(e.type==="auxclick"&&e.button!==1)return;let t,i,n=e.target;for(let c=0;c<=3&&n;c++){if(n.tagName?.toLowerCase()==="form")return;x(n)&&(t=n),T(n)&&(i=n),n=n.parentNode}if(!i)return;let a=D(i);t&&(a.props.url=t.href),f(a)}function Q(e){let t=e.target;(t.hasAttribute("novalidate")||t.checkValidity())&&!y(t,0)&&g("Form: Submission")}function X(e){let t=D(e.target);t.name&&f(t)}function ee(){document.addEventListener("click",_),document.addEventListener("auxclick",_),Array.isArray(o.fileDownloads?.fileExtensions)&&(P=o.fileDownloads.fileExtensions),o.formSubmissions&&document.addEventListener("submit",Q,!0),document.addEventListener("submit",X),document.addEventListener("click",R),document.addEventListener("auxclick",R)}function h(e){!o.hashBasedRouting&&e&&m===location.pathname||(m=location.pathname,g("pageview"))}function b(){h(!0)}function te(...e){C.apply(this,e),b()}function ne(){!m&&document.visibilityState==="visible"&&h()}function ie(e){e.persisted&&h()}function oe(){o.hashBasedRouting?window.addEventListener("hashchange",b):(C=window.history.pushState,window.history.pushState=te,window.addEventListener("popstate",b)),document.visibilityState==="hidden"||document.visibilityState==="prerender"?document.addEventListener("visibilitychange",ne):h(),window.addEventListener("pageshow",ie)}function re(e){$(e||{}),j(),o.autoCapturePageviews&&oe(),ee(),o.bindToWindow&&(window.thebase??(window.thebase={}),window.thebase.track=g,window.thebase.track.s="npm",window.thebase.track.v=36,window.thebase.track.l=!0)}export{H as DEFAULT_FILE_TYPES,re as init,g as track,ae as visitorContext};