@valancex/cli 0.0.0-stage → 0.12.0

package/schemas/valance.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://valancex.dev/schemas/valance.schema.json",
+  "title": "valance.json",
+  "description": "The project: what the application is called. Settings for a target are in valance.<target>.json (valance.web.json for the web).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "name"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1,
+      "description": "The version of this file's format."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The application's name: the site's title in navigation and in every page's <title>."
+    },
+    "title": {
+      "type": "string",
+      "default": "{page} \u00b7 {site}",
+      "pattern": "^[^{}]*(\\{page\\}|\\{site\\})[^{}]*(\\{page\\}|\\{site\\}|[^{}])*$",
+      "maxLength": 120,
+      "description": "How a document's title is written: \"{page}\" is the page's title and \"{site}\" the name above. Must contain \"{page}\". A page whose title is the site's name is that name alone."
+    }
+  }
+}

package/schemas/valance.web.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://valancex.dev/schemas/valance.web.schema.json",
+  "title": "valance.web.json",
+  "description": "Settings for the web target: where the built site is served.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1,
+      "description": "The version of this file's format."
+    },
+    "base": {
+      "type": "string",
+      "pattern": "^/([\\w.~-]+/)*$",
+      "default": "/",
+      "description": "The path the site is served under: \"/\" or \"/docs/\". Every address the build writes is under it."
+    },
+    "url": {
+      "type": "string",
+      "pattern": "^https?://.*[^/]$",
+      "description": "Where the site is published, without a trailing slash. With it, pages get canonical links and the build writes sitemap.xml."
+    },
+    "headers": {
+      "type": "boolean",
+      "default": true,
+      "description": "Write the recommended security headers (a strict Content-Security-Policy and others) as _headers beside the built site."
+    },
+    "announce": {
+      "type": "boolean",
+      "default": true,
+      "description": "After the application changes page in place, tell assistive technology: say the new title in a live region and focus the main content."
+    },
+    "api": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "base"
+      ],
+      "description": "The application's backend.",
+      "properties": {
+        "base": {
+          "type": "string",
+          "description": "Where its requests go: a path on the site's own origin (\"/api\") or an absolute https address (\"https://api.example.com\", which the Content-Security-Policy then allows)."
+        },
+        "proxy": {
+          "type": "string",
+          "description": "For vlx dev: forward requests under a path \"base\" to this address (\"http://localhost:3000\"), so the browser sees one origin and no CORS settings are needed."
+        }
+      }
+    }
+  }
+}

package/templates/web/README.md

@@ -0,0 +1,14 @@
+# {{name}}
+
+A VALANCE application for the web, made with `vlx init`.
+
+```console
+$ {{run}} dev      # serve it, and rebuild as you edit
+$ {{run}} build    # write the site to dist/
+$ {{run}} check    # find mistakes in your files without building
+```
+
+- `content/` is Markdown: a page's path is its address.
+- `src/layout.mprx` is the page around it; `src/main.ts` declares the components it uses (start reading there).
+- `src/styles.css` is the look. `public/` is served as it is.
+- `valance.json` names the application{{web_note}}.

package/templates/web/content/404.md

@@ -0,0 +1,7 @@
+---
+title: Not found
+---
+
+# Not found
+
+There is no page at this address. [Back to the start](/).

package/templates/web/content/guide/getting-started.md

@@ -0,0 +1,33 @@
+---
+title: Getting started
+description: Create the project, run it, change a page.
+order: 1
+---
+
+# Getting started
+
+## Run it
+
+```
+pnpm install
+pnpm dev
+```
+
+Open the address `vlx dev` prints. Edit this file and save: the page reloads with your change.
+
+## Build it
+
+```
+pnpm build
+```
+
+The finished site is in `dist/`. Anything that serves files can host it.
+
+## Where things are
+
+1. `content/` holds the pages.
+2. `src/layout.mprx` is the shell around every page.
+3. `src/styles.css` is the look.
+4. `public/` holds files that are served as they are, like the logo.
+
+Next: [writing pages](./writing-pages.md).

package/templates/web/content/guide/writing-pages.md

@@ -0,0 +1,21 @@
+---
+title: Writing pages
+description: Front matter, headings, links and images.
+order: 2
+---
+
+# Writing pages
+
+A page starts with an optional block of settings, then Markdown.
+
+## Front matter
+
+`title`, `description` and `order` are the three settings. Without a `title`, the first `#` heading is used.
+
+> Anything else in the front matter is an error, so a typo never goes unnoticed.
+
+## Links and images
+
+Link to another page by its address, like [Getting started](/guide/getting-started), or by its file, like [the first page](./getting-started.md). A link that leads nowhere fails the build and names the line.
+
+Images live in `public/` and are named from the site's root: `![Alt text](/logo.svg)`.

package/templates/web/content/index.md

@@ -0,0 +1,16 @@
+---
+title: {{name}}
+description: A small documentation site, written the way a VALANCE application is written.
+---
+
+# {{name}}
+
+![The {{name}} logo](/logo.svg)
+
+This site is a **VALANCE application**. Everything you are reading is a Markdown file in `content/`; the page around it is `src/layout.mprx`; the look is `src/styles.css`.
+
+- Pages are Markdown files. Their path is their address.
+- The layout and the components are templates.
+- `vlx dev` serves the site and updates it as you edit.
+
+Start with [Getting started](/guide/getting-started), or see [how a page is written](/guide/writing-pages#front-matter).

package/templates/web/gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.valance
+.work*

package/templates/web/public/logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="{{name}}"><rect width="64" height="64" rx="14" fill="#5b3fd6"/><path d="M18 20h28M18 32h28M18 44h18" stroke="#fff" stroke-width="5" stroke-linecap="round"/></svg>

package/templates/web/src/layout.mprx

@@ -0,0 +1,27 @@
+<shell class="layout" theme={theme}>
+  <header class="bar">
+    <link class="brand" href={home} current="false">{site}</link>
+    <theme-toggle theme={theme} on.toggle={toggleTheme()} />
+  </header>
+  <div class="frame">
+    <nav class="sidebar" label="Pages">
+      {#each sections as s (s.id)}
+        <section>
+          {#if s.title != ""}<para class="nav-title">{s.title}</para>{/if}
+          <list class="nav-list">
+            {#each s.items as n (n.id)}
+              <item><link class="nav-link" href={n.href} current={n.current}>{n.label}</link></item>
+            {/each}
+          </list>
+        </section>
+      {/each}
+    </nav>
+    <main id="content" tabindex="-1">
+      <blocks items={blocks} />
+      <nav class="pager" label="Previous and next page">
+        {#if prev.href != ""}<link class="pager-link" href={prev.href} current="false">{prev.label}</link>{/if}
+        {#if next.href != ""}<link class="pager-link" href={next.href} current="false">{next.label}</link>{/if}
+      </nav>
+    </main>
+  </div>
+</shell>

package/templates/web/src/main.ts

@@ -0,0 +1,20 @@
+import { component, defineApp, field } from "@valancex/common";
+import { Schema } from "effect";
+import layout from "./layout.mprx";
+import themeToggle from "./theme-toggle.js";
+
+// The application, from the top. `layout` is the page's shell; `components` lists the components your templates use, once each: a template uses one by writing its tag. Nothing under src/ is part of
+// the application unless it is imported here and listed. A component states its own interface where it is defined (see theme-toggle.ts).
+export default defineApp({
+  layout: component(layout),
+  components: [themeToggle],
+
+  // The application's own state, beyond "which page is shown": each field is its type and its default, together. A field is a name the layout can read (`theme`), and the commands below are
+  // names it can run (`toggleTheme()`).
+  state: {
+    theme: field(Schema.Literal("light", "dark"), "light"),
+  },
+  commands: (command) => ({
+    toggleTheme: command((state) => ({ ...state, theme: state.theme === "light" ? "dark" : "light" })),
+  }),
+});

package/templates/web/src/styles.css

@@ -0,0 +1,28 @@
+:root { --bg: #fff; --fg: #1d2330; --muted: #5c6578; --line: #e3e6ee; --accent: #5b3fd6; --code: #f4f5f9; }
+[data-theme="dark"] { --bg: #12141b; --fg: #e8eaf1; --muted: #9aa3b8; --line: #272b38; --accent: #a78bfa; --code: #1b1e29; }
+
+* { box-sizing: border-box; }
+body { margin: 0; font: 16px/1.6 system-ui, sans-serif; background: var(--bg); color: var(--fg); }
+.layout { min-height: 100vh; background: var(--bg); color: var(--fg); }
+
+.bar { display: flex; align-items: center; justify-content: space-between; padding: 0.75rem 1.5rem; border-bottom: 1px solid var(--line); }
+.brand { font-weight: 700; color: var(--fg); text-decoration: none; }
+.theme-toggle { font: inherit; padding: 0.25rem 0.75rem; border: 1px solid var(--line); border-radius: 999px; background: transparent; color: var(--fg); cursor: pointer; }
+
+.frame { display: grid; grid-template-columns: 14rem 1fr; gap: 2rem; max-width: 60rem; margin: 0 auto; padding: 1.5rem; }
+.sidebar { font-size: 0.95rem; }
+.nav-title { margin: 1rem 0 0.25rem; font-weight: 600; color: var(--muted); text-transform: uppercase; font-size: 0.75rem; letter-spacing: 0.05em; }
+.nav-list { list-style: none; margin: 0; padding: 0; }
+.nav-link { display: block; padding: 0.15rem 0; color: var(--fg); text-decoration: none; }
+.nav-link[aria-current="page"] { color: var(--accent); font-weight: 600; }
+
+main { min-width: 0; }
+main h1 { margin-top: 0; }
+a { color: var(--accent); }
+.code { padding: 1rem; overflow-x: auto; background: var(--code); border-radius: 0.5rem; }
+code { font-family: ui-monospace, monospace; font-size: 0.9em; }
+.quote { margin: 1rem 0; padding-left: 1rem; border-left: 3px solid var(--accent); color: var(--muted); }
+.picture { max-width: 100%; }
+.pager { display: flex; justify-content: space-between; margin-top: 3rem; padding-top: 1rem; border-top: 1px solid var(--line); }
+
+@media (max-width: 40rem) { .frame { grid-template-columns: 1fr; } }

package/templates/web/src/theme-toggle.mprx

@@ -0,0 +1 @@
+<button class="theme-toggle" pressed={theme == "dark" ? "true" : "false"} on.click={toggle()}>{theme == "dark" ? "Light" : "Dark"}</button>

package/templates/web/src/theme-toggle.ts

@@ -0,0 +1,10 @@
+import { component } from "@valancex/common";
+import { Schema } from "effect";
+import template from "./theme-toggle.mprx";
+
+// The interface of `<theme-toggle>`, stated once, where it is defined: what the template reads (`theme`) and what it raises (`toggle`, which carries nothing). Whoever uses it names only that
+// they use it. `.valance/templates.d.ts` gives the template its keys as a type, so a contract that disagrees with the template is an error in the editor.
+export default component(template, {
+  props: { theme: Schema.Literal("light", "dark") },
+  events: { toggle: Schema.Void },
+});

package/templates/web/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "types": ["node"],
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "allowArbitraryExtensions": true,
+    "rootDirs": ["src", ".valance/types"]
+  },
+  "include": ["src"]
+}

package/views/block.mprx

@@ -0,0 +1,3 @@
+<mesh-fragment>
+  {#if b.kind == "heading"}<heading level={b.level} anchor={b.anchor} spans={b.spans} />{:else if b.kind == "list"}<list-block ordered={b.ordered} items={b.items} />{:else if b.kind == "code"}<pre class="code" tabindex="0"><code>{b.text}</code></pre>{:else if b.kind == "quote"}<quote class="quote"><runs spans={b.spans} /></quote>{:else if b.kind == "image"}<image class="picture" src={b.src} alt={b.alt} loading="lazy" />{:else}<para class="prose"><runs spans={b.spans} /></para>{/if}
+</mesh-fragment>

package/views/blocks.mprx

@@ -0,0 +1,3 @@
+<mesh-fragment>
+  {#each items as b (b.id)}<block b={b} />{/each}
+</mesh-fragment>

package/views/heading.mprx

@@ -0,0 +1,3 @@
+<mesh-fragment>
+  {#if level == 1}<h1 id={anchor}><runs spans={spans} /></h1>{:else if level == 2}<h2 id={anchor}><runs spans={spans} /></h2>{:else}<h3 id={anchor}><runs spans={spans} /></h3>{/if}
+</mesh-fragment>

package/views/inline.mprx

@@ -0,0 +1,3 @@
+<mesh-fragment>
+  {#if kind == "strong"}<strong>{text}</strong>{:else if kind == "emphasis"}<em>{text}</em>{:else if kind == "code"}<code>{text}</code>{:else if kind == "link"}<a href={href}>{text}</a>{:else}<mesh-fragment>{text}</mesh-fragment>{/if}
+</mesh-fragment>

package/views/layout.mprx

@@ -0,0 +1,26 @@
+<shell class="layout" theme="light">
+  <header class="bar">
+    <link class="brand" href={home} current="false">{site}</link>
+  </header>
+  <div class="frame">
+    <nav class="sidebar" label="Pages">
+      {#each sections as s (s.id)}
+        <section>
+          {#if s.title != ""}<para class="nav-title">{s.title}</para>{/if}
+          <list class="nav-list">
+            {#each s.items as n (n.id)}
+              <item><link class="nav-link" href={n.href} current={n.current}>{n.label}</link></item>
+            {/each}
+          </list>
+        </section>
+      {/each}
+    </nav>
+    <main id="content" tabindex="-1">
+      <blocks items={blocks} />
+      <nav class="pager" label="Previous and next page">
+        {#if prev.href != ""}<link class="pager-link" href={prev.href} current="false">{prev.label}</link>{/if}
+        {#if next.href != ""}<link class="pager-link" href={next.href} current="false">{next.label}</link>{/if}
+      </nav>
+    </main>
+  </div>
+</shell>

package/views/list-block.mprx

@@ -0,0 +1,5 @@
+<mesh-fragment>
+  {#if ordered}
+    <olist class="list"><list-items items={items} /></olist>{:else}
+    <list class="list"><list-items items={items} /></list>{/if}
+</mesh-fragment>

package/views/list-items.mprx

@@ -0,0 +1,3 @@
+<mesh-fragment>
+  {#each items as i (i.id)}<item><runs spans={i.spans} /></item>{/each}
+</mesh-fragment>

package/views/runs.mprx

@@ -0,0 +1,3 @@
+<mesh-fragment>
+  {#each spans as s (s.id)}<inline kind={s.kind} text={s.text} href={s.href} />{/each}
+</mesh-fragment>