@threadlabs/markupkit 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Next Web Working Group
+
+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

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/threadlabs-studio/markupkit/main/website/public/logo-dark.svg">
+  <img src="https://raw.githubusercontent.com/threadlabs-studio/markupkit/main/website/public/logo.svg" alt="MarkupKit logo" width="80" height="80">
+</picture>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# MarkupKit
+
+Build with HTML again.
+
+The HTML, CSS, and JavaScript you know, with components, routing, and server rendering powered by
+the next generation of HTML. MarkupKit also provides shared layouts and typed data for your application.
+
+MarkupKit is a Threadlabs product, built on [HTML Next](https://github.com/nextwebwg/html-next),
+the implementation of the Next Web Working Group's declarative components proposal.
+[Markupress](https://github.com/threadlabs-studio/markupress) builds documentation on MarkupKit;
+MarkupKit owns the application platform and Markupress owns the documentation experience.
+
+MarkupKit (`@threadlabs/markupkit`) builds applications with HTML Next components. It provides routes,
+layouts, server loaders, endpoints, middleware, browser delivery, and development tools. A build
+prerenders pages for any static host and writes a request server for pages that render on each
+request, which `markupkit start` runs on Node and Deno and Bun run through its `fetch`.
+[The server-rendering design](./docs/server-rendering.md) records how requests are answered.
+
+Use Node `>=22.22.2 <23 || >=24.15 <25`. Install `@threadlabs/markupkit` and add its commands to your
+`package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "dev": "markupkit dev",
+    "build": "markupkit build",
+    "preview": "markupkit preview",
+    "start": "markupkit start"
+  }
+}
+```
+
+Then run `pnpm dev`, `pnpm build`, `pnpm preview`, or `pnpm start` (`npm run dev` and the others work too).
+
+**Guide:** [MarkupKit](https://threadlabs-studio.github.io/markupkit/) covers pages and routing,
+loading data, endpoints and middleware, navigation, moving between pages, deployment, and
+configuration. Its source is
+[`website/docs`](./website/docs/) in this repository, built with Markupress.
+[The client-navigation design](./docs/client-navigation.md) records how pages swap in place.
+
+## Proof applications
+
+From this repository, after building:
+
+```sh
+node dist/cli.js build examples/basic
+node dist/cli.js preview examples/basic
+pnpm build:docs-proof
+node dist/cli.js preview .context/markupkit-docs-proof
+```
+
+The basic application exercises routes, loaders, state, and component modules without documentation
+features. The docs proof converts this repository's Markdown guides and generates a component
+reference, code display, heading anchors, search navigation, a theme, and an interactive example.
+Its Markdown dependency and theme live in the consumer, outside the platform runtime and published
+package. Its input is trusted, checked-in author content; it does not sanitize arbitrary Markdown.
+
+MarkupKit is MIT-licensed.

package/components/breadcrumbs.html

@@ -0,0 +1,9 @@
+<template component="mk-breadcrumbs">
+  <defs>
+    <prop name="items" type="list(object({ href: string, label: string, current: string, depth: number, pageName: string, group?: string, ... }))" required>Pages from the top of the trail to the current page.</prop>
+    <prop name="label" type="string" default="Breadcrumb">Accessible navigation name.</prop>
+  </defs>
+  <nav from:aria-label="$label">
+    <ol><li $each="item of $items"><a from:href="$item.href" from:aria-current="$item.current">{$item.label}</a></li></ol>
+  </nav>
+</template>

package/components/nav.html

@@ -0,0 +1,51 @@
+<template component="mk-nav-items">
+  <defs>
+    <prop name="items" type="list(object({ label: string, current: string, depth: number, href?: string, group?: string, open?: boolean, children?: list(object({ label: string, ... })), ... }))" required>Navigation items, each with its nested items.</prop>
+  </defs>
+  <ul><template $each="item, index of $items">
+    <li $if="$item.group and $item.group != $items[$index - 1].group" data-group from:data-depth="$item.depth">{$item.group}</li>
+    <li from:data-depth="$item.depth">
+      <template $match><details $when="$item.children" from:open="$item.open">
+        <summary><template $match><a $when="$item.href" from:href="$item.href" from:aria-current="$item.current">{$item.label}</a><span $else>{$item.label}</span></template></summary>
+        <mk-nav-items from:items="$item.children"></mk-nav-items>
+      </details>
+      <a $else from:href="$item.href" from:aria-current="$item.current">{$item.label}</a></template>
+    </li>
+  </template></ul>
+</template>
+<!-- The first three levels of items render inline, each as <mk-nav-items> renders a level, so a tree up to
+  three levels deep is one instance and the page carries its items once. Each deeper level is an <mk-nav-items>. -->
+<template component="mk-nav">
+  <defs>
+    <prop name="items" type="list(object({ label: string, current: string, depth: number, href?: string, group?: string, open?: boolean, children?: list(object({ label: string, ... })), ... }))" required>Ordered page links: navigation() items, or navigationTree() nodes.</prop>
+    <prop name="label" type="string" default="Navigation">Accessible navigation name.</prop>
+  </defs>
+  <nav from:aria-label="$label"><ul><template $each="a, i of $items">
+    <li $if="$a.group and $a.group != $items[$i - 1].group" data-group from:data-depth="$a.depth">{$a.group}</li>
+    <li from:data-depth="$a.depth">
+      <template $match><details $when="$a.children" from:open="$a.open">
+        <summary><template $match><a $when="$a.href" from:href="$a.href" from:aria-current="$a.current">{$a.label}</a><span $else>{$a.label}</span></template></summary>
+        <ul><template $each="b, j of $a.children">
+          <li $if="$b.group and $b.group != $a.children[$j - 1].group" data-group from:data-depth="$b.depth">{$b.group}</li>
+          <li from:data-depth="$b.depth">
+            <template $match><details $when="$b.children" from:open="$b.open">
+              <summary><template $match><a $when="$b.href" from:href="$b.href" from:aria-current="$b.current">{$b.label}</a><span $else>{$b.label}</span></template></summary>
+              <ul><template $each="c, k of $b.children">
+                <li $if="$c.group and $c.group != $b.children[$k - 1].group" data-group from:data-depth="$c.depth">{$c.group}</li>
+                <li from:data-depth="$c.depth">
+                  <template $match><details $when="$c.children" from:open="$c.open">
+                    <summary><template $match><a $when="$c.href" from:href="$c.href" from:aria-current="$c.current">{$c.label}</a><span $else>{$c.label}</span></template></summary>
+                    <mk-nav-items from:items="$c.children"></mk-nav-items>
+                  </details>
+                  <a $else from:href="$c.href" from:aria-current="$c.current">{$c.label}</a></template>
+                </li>
+              </template></ul>
+            </details>
+            <a $else from:href="$b.href" from:aria-current="$b.current">{$b.label}</a></template>
+          </li>
+        </template></ul>
+      </details>
+      <a $else from:href="$a.href" from:aria-current="$a.current">{$a.label}</a></template>
+    </li>
+  </template></ul></nav>
+</template>

package/components/pager.html

@@ -0,0 +1,13 @@
+<template component="mk-pager">
+  <defs>
+    <prop name="previous" type="object({ href: string, label: string, current: string, depth: number, pageName: string, group?: string, ... })">The page before this one.</prop>
+    <prop name="next" type="object({ href: string, label: string, current: string, depth: number, pageName: string, group?: string, ... })">The page after this one.</prop>
+    <prop name="label" type="string" default="Pages">Accessible navigation name.</prop>
+    <prop name="previousText" type="string" default="Previous">Text before the previous page's label.</prop>
+    <prop name="nextText" type="string" default="Next">Text before the next page's label.</prop>
+  </defs>
+  <nav from:aria-label="$label">
+    <a $if="$previous" rel="prev" from:href="$previous.href"><small>{$previousText}</small> {$previous.label}</a>
+    <a $if="$next" rel="next" from:href="$next.href"><small>{$nextText}</small> {$next.label}</a>
+  </nav>
+</template>

package/dist/application.d.ts

@@ -0,0 +1,31 @@
+import { type ComponentDefinition } from "@nextwebwg/html-next";
+import { type ViteDevServer } from "vite";
+import { type PageAssets } from "./document.js";
+import { type RenderLayer } from "./server.js";
+import type { Application, ApplicationOptions, ContentSecurityPolicyOptions, RenderedPolicy, ApplicationRoute, BrowserDefinition, RenderedHead, RenderedPage } from "./types.js";
+export declare function headScripts(options: ApplicationOptions, root: string): Promise<readonly string[]>;
+export declare function notFoundPage(scripts: readonly string[], policy?: RenderedPolicy): {
+    head: RenderedHead;
+    body: string;
+    html: string;
+};
+/** A route's components, ready to render: its layers, every component they use, and their browser delivery. */
+export interface RouteGraph {
+    readonly layers: readonly RenderLayer[];
+    readonly definitions: readonly ComponentDefinition[];
+    readonly components: readonly BrowserDefinition[];
+}
+/** The application, plus what a build reads from it: each route's component graph and the concrete page URLs. */
+export declare function createApplicationInternals(input?: ApplicationOptions, moduleServer?: ViteDevServer, assets?: (page: RenderedPage) => PageAssets, policy?: ContentSecurityPolicyOptions | false): Promise<{
+    application: Application;
+    graph: (route: ApplicationRoute) => Promise<RouteGraph>;
+    catalog: () => Promise<ReadonlyMap<string, ApplicationRoute>>;
+    policy: () => Promise<RenderedPolicy | undefined>;
+    redirects: Map<string, string>;
+}>;
+/**
+ * assets supplies a serving adapter's browser modules and stylesheets for fetch(), and policy the csp
+ * option it applies in place of the configured one, as the development server adds what Vite needs.
+ */
+export declare function createApplication(input?: ApplicationOptions, moduleServer?: ViteDevServer, assets?: (page: RenderedPage) => PageAssets, policy?: ContentSecurityPolicyOptions | false): Promise<Application>;
+//# sourceMappingURL=application.d.ts.map

package/dist/application.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../src/application.ts"],"names":[],"mappings":"AAKA,OAAO,EAA0D,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAGxH,OAAO,EAA0C,KAAK,aAAa,EAAE,MAAM,MAAM,CAAC;AAIlF,OAAO,EAA4C,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAM1F,OAAO,EAA2K,KAAK,WAAW,EAAE,MAAM,aAAa,CAAC;AACxN,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,4BAA4B,EAAiB,cAAc,EAAE,gBAAgB,EAAE,iBAAiB,EAA0D,YAAY,EAAE,YAAY,EACvM,MAAM,YAAY,CAAC;AAoB/C,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAYvG;AAGD,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,cAAc;;;;EAI/E;AAED,+GAA+G;AAC/G,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACrD,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACnD;AAED,iHAAiH;AACjH,wBAAsB,0BAA0B,CAAC,KAAK,GAAE,kBAAuB,EAAE,YAAY,CAAC,EAAE,aAAa,EAC3G,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,UAAU,EAAE,MAAM,CAAC,EAAE,4BAA4B,GAAG,KAAK;;mBAgF9D,gBAAgB,KAAG,OAAO,CAAC,UAAU,CAAC;;;;GAyPnE;AA+CD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,GAAE,kBAAuB,EAAE,YAAY,CAAC,EAAE,aAAa,EAClG,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,UAAU,EAAE,MAAM,CAAC,EAAE,4BAA4B,GAAG,KAAK,GAAG,OAAO,CAAC,WAAW,CAAC,CAElH"}