brut 0.0.20 → 0.0.22

data/brut-js/src/testing/AssetMetadata.js

@@ -0,0 +1,35 @@
+import fs from "node:fs"
+import path from "node:path"
+/**
+ * Provides structured access to the asset metadata for a BrutRB app. This is used to allow custom elements
+ * to be defined in JSDOM the same way they are in a real browser.
+ *
+ * @memberof testing
+ */
+class AssetMetadata {
+  constructor(parsedJSON, publicRoot) {
+    this.assetMetadata = parsedJSON.asset_metadata
+    this.publicRoot    = publicRoot
+  }
+
+  scriptURLs() {
+    return Object.entries(this.assetMetadata[".js"]).map( (entry) => {
+      return entry[0] 
+    })
+  }
+
+  fileContainingScriptURL(scriptURL) {
+    const file = Object.entries(this.assetMetadata[".js"]).find( (entry) => {
+      return entry[0] == scriptURL
+    })
+    if (!file || !file[1]) {
+      return null
+    }
+    let relativePath = file[1]
+    if (relativePath[0] == "/") {
+      relativePath = relativePath.slice(1)
+    }
+    return fs.readFileSync(path.resolve(this.publicRoot,relativePath))
+  }
+}
+export default AssetMetadata

data/brut-js/src/testing/AssetMetadataLoader.js

@@ -0,0 +1,25 @@
+import { ResourceLoader } from "jsdom"
+
+/**
+ * An JSDOM resource loader based on BrutRB asset metadata.
+ *
+ * @memberof testing
+ */
+class AssetMetadataLoader extends ResourceLoader {
+  constructor(assetMetadata) {
+    super()
+    this.assetMetadata = assetMetadata
+  }
+
+  fetch(url,options) {
+    const parsedURL = new URL(url)
+    const jsContents = this.assetMetadata.fileContainingScriptURL(parsedURL.pathname)
+    if (jsContents) {
+      return Promise.resolve(jsContents)
+    }
+    else {
+      return super.fetch(url,options)
+    }
+  }
+}
+export default AssetMetadataLoader

data/brut-js/src/testing/CustomElementTest.js

@@ -0,0 +1,235 @@
+import DOMCreator from "./DOMCreator.js"
+import assert from "assert"
+/**
+ * The class that implements a test case.  Typically, an instance of this is created for you and you call `test` on that to write your
+ * test case.
+ * @memberof testing
+ */
+class CustomElementTest {
+  constructor(html, queryString, assetMetadata) {
+    this.html          = html
+    this.queryString   = queryString
+    this.fetchBehavior = {}
+    this.assetMetadata = assetMetadata
+  }
+
+  /**
+   * Configure a query string to be present when the custom elements are defined and connected.
+   */
+  andQueryString(queryString) {
+    this.queryString = queryString
+    return this
+  }
+
+  /**
+   * Configure behavior when #{link external:fetch} is called, since it's not implemented by JSDom or NodeJS.
+   *
+   * @param {String} url - the URL that is expected. This should be a relative URL, as that is all that is currently supported. This
+   * URL must match exactly to a `fetch` call.
+   * @param {Object} behavior - an object describing what you want to happen when `url` is fetched.  This currently supports only a
+   * few rudimentary behaviors:
+   * * `{then: { ok: { text: "some text" } } }` - This will return an "ok" response whose body is the given text, available only as
+   * text.
+   * * `{then: { status: XXX, text: "some text" }}` - This will return the given http status, with `ok` as true if it's 2xx or 3xx. If `text` is given, that will be available as text only.
+   */
+  onFetch(url,behavior) {
+    if (!this.fetchBehavior[url]) {
+      this.fetchBehavior[url] = {
+        numCalls: 0,
+        responses: [],
+      }
+    }
+    if (behavior instanceof Array) {
+      behavior.forEach( (b) =>  {
+        this.fetchBehavior[url].responses.push(b)
+      })
+    }
+    else {
+      this.fetchBehavior[url].responses.push(behavior)
+    }
+    return this
+  }
+
+  /** Comment out a test without using code comments */
+  xtest() {
+    return this
+  }
+
+
+  /** Declare a test to run with the previously-defined HTML, query string, and fetch behavior.
+   *
+   * @param {String} description - a description of the test.
+   * @param {testCodeCallback} testCode - a function containing the code for your test.
+   */
+  test(description,testCode) {
+    it(description, () => {
+      const domCreator = new DOMCreator(this.assetMetadata)
+      const dom = domCreator.create({
+        html: this.html,
+        queryString: this.queryString
+      })
+      const fetchRequests = []
+
+      dom.window.Request = Request
+      dom.window.fetch = (request) => {
+        const url = new URL(request.url)
+        const path = url.pathname + url.search
+        const behaviors = this.fetchBehavior[path]
+        if (!behaviors) {
+          throw `fetch() called with ${path}, which was not configured`
+        }
+        if (behaviors.numCalls > behaviors.responses.length) {
+          throw `fetch() called ${behaviors.numCalls} times, but we only have ${behaviors.response.length} responses configured`
+        }
+        const behavior = behaviors.responses[behaviors.numCalls]
+        behaviors.numCalls++
+
+        let promise = null
+
+        if (behavior.then) {
+          if (behavior.then.ok) {
+            if (behavior.then.ok.text) {
+              const response = {
+                ok: true,
+                text: () => {
+                  return Promise.resolve(behavior.then.ok.text)
+                }
+              }
+              promise = Promise.resolve(response)
+            }
+            else {
+              throw `unknown fetch behavior: expected then.ok.text: ${JSON.stringify(behavior)}`
+            }
+          }
+          else if (behavior.then.status) {
+            let ok = false
+            if ((behavior.then.status >= 200) && (behavior.then.status < 400) ){
+              ok = true
+            }
+            const response = {
+              ok: ok,
+              status: behavior.then.status,
+                text: () => {
+                  return Promise.resolve(behavior.then.text)
+                }
+            }
+            promise = Promise.resolve(response)
+          }
+          else {
+            throw `unknown fetch behavior: expected then.ok or then.status: ${JSON.stringify(behavior)}`
+          }
+        }
+        else {
+          throw `unknown fetch behavior: expected then: ${JSON.stringify(behavior)}`
+        }
+        request.promiseReturned = promise
+        fetchRequests.push(request)
+        return promise
+      }
+
+      const window = dom.window
+      const document = window.document
+      let returnValue = null
+      return new Promise( (resolve, reject) => {
+        dom.window.addEventListener("load", () => {
+          try {
+            const paramsGivenToTest = {
+              window,
+              document,
+              assert,
+              fetchRequests,
+              waitForSetTimeout: this.#waitForSetTimeout,
+              readRequestBodyIntoJSON: this.#readRequestBodyIntoJSON,
+              readRequestBodyIntoString: this.#readRequestBodyIntoString,
+            }
+            returnValue = testCode(paramsGivenToTest)
+            if (returnValue) {
+              resolve(returnValue)
+            }
+            else {
+              resolve()
+            }
+          } catch (e) {
+            reject(e)
+          }
+        })
+      })
+    })
+    return this
+  }
+
+  /** Used to wait for a few milliseconds before performing further assertions.
+   * This can be useful when a custom element has `setTimeout` calls
+   */
+  #waitForSetTimeout = (ms) => {
+    return new Promise( (resolve) => {
+      setTimeout(resolve,ms)
+    })
+  }
+
+  /**
+   * Given a fetch request (available via `fetchRequests` passed to your test), turn the body into JSON
+   * and return a promise with the JSON.  To use this in a test, you must include your assertions inside
+   * the `then` of the returned promise and you *must* return that from your test.
+   *
+   * @example
+   * withHTML(
+   *   "<div-makes-a-fetch>"
+   * ).onFetch("/foo", { then: { status: 200 }}
+   * ).test("a test",({assert,fetchRequests}) => {
+   *   assert.equal(fetchRequests.length,1)
+   *   return readRequestBodyIntoJSON(fetchRequests[0]).then( (json) => {
+   *     assert.equal(json["foo"],"bar")
+   *   })
+   * })
+   */
+  #readRequestBodyIntoJSON = (request) => {
+    return this.#readRequestBodyIntoString(request).then( (string) => {
+      try {
+        const json = JSON.parse(string)
+        return Promise.resolve(json)
+      }
+      catch (e) {
+        assert(false,`'${string}' could not be parsed as JSON`)
+      }
+      return Promise.resolve()
+    })
+  }
+
+  /**
+   * Given a fetch request (available via `fetchRequests` passed to your test), turn the body into a string
+   * and return a promise with the string.  To use this in a test, you must include your assertions inside
+   * the `then` of the returned promise and you *must* return that from your test.
+   *
+   * @example
+   * withHTML(
+   *   "<div-makes-a-fetch>"
+   * ).onFetch("/foo", { then: { status: 200 }}
+   * ).test("a test",({assert,fetchRequests}) => {
+   *   assert.equal(fetchRequests.length,1)
+   *   return readRequestBodyIntoString(fetchRequests[0]).then( (string) => {
+   *     assert.equal(string,"foo")
+   *   })
+   * })
+   */
+  #readRequestBodyIntoString = (request) => {
+    const reader = request.body.getReader()
+    const utf8Decoder = new TextDecoder("utf-8");
+    let string = ""
+    const parse = ({value,done}) => {
+      if (done) {
+        return Promise.resolve(string)
+      }
+      else {
+        if (value) {
+          string = string + utf8Decoder.decode(value, { stream: true })
+        }
+        return reader.read().then(parse)
+      }
+    }
+    return reader.read().then(parse)
+  }
+
+
+}
+export default CustomElementTest

data/brut-js/src/testing/DOMCreator.js

@@ -0,0 +1,45 @@
+import { JSDOM, VirtualConsole } from "jsdom"
+
+import AssetMetadataLoader from "./AssetMetadataLoader.js"
+
+/**
+ * Creates a JSDOM based on the the given HTML and query string.
+ *
+ * @memberof testing
+ */
+class DOMCreator {
+  constructor(assetMetadata) {
+    this.assetMetadata = assetMetadata
+  }
+
+  create({html,queryString}) {
+
+    const resourceLoader = new AssetMetadataLoader(this.assetMetadata)
+
+
+    const url = "http://example.com" + ( queryString ? `?${queryString}` : "" )
+
+    const scripts = this.assetMetadata.scriptURLs().map( (url) => `<script src="${url}"></script>` )
+    const virtualConsole = new VirtualConsole()
+    virtualConsole.sendTo(console);
+    return new JSDOM(
+      `<!DOCTYPE html>
+        <html>
+        <head>
+        ${scripts}
+        </head>
+        <body>
+        ${html}
+        </body>
+        </html>
+        `,{
+          resources: "usable",
+          runScripts: "dangerously",
+          includeNodeLocations: true,
+          resources: resourceLoader,
+          url: url
+        }
+    )
+  }
+}
+export default DOMCreator

data/brut-js/src/testing/index.js

@@ -0,0 +1,48 @@
+/**
+ * Enables and implements a basic testing system for custom elements. This uses JSDOM and some hacks to allow
+ * you to test your custom elements using a DOM-like experience, but without having to run a real browser.
+ * It is designed to have very few dependencies to ensure the least amount of configuration and tool
+ * debt.
+ *
+ * It assumes you are using Mocha.  To create a test, create a file named `Whatever.spec.js` in the folder where you are running
+ * Mocha.  Convention is that `Whatever` is the name of your custom element's class.
+ *
+ * @example
+ * import { withHTML } from "../src/testing/index.js"
+ *
+ * describe("<some-element>", () => {
+ *   withHTML(`
+ *   <some-element>OK</some-element>
+ *   `).test("lower-cases its contents", ({document,assert}) => {
+ *     const element = document.querySelector("some-element")
+ *     assert.equal(element.textContent,"ok")
+ *   })
+ * })
+ *
+ * @module testing
+ */
+import AssetMetadata from "./AssetMetadata.js"
+import CustomElementTest from "./CustomElementTest.js"
+
+/**
+ * Bootstraps a test based on some HTML and configuration about where the bundled custom elements are. It's recommended that you
+ * create the method `withHTML` in your `SpecHelper.js` file to set up the asset metadata stuff.
+ *
+ * This returns a {@link module:testing~CustomElementTest}, on which you can call additional setup methods, or start defining tests with the 
+ * {@link module:testing~CustomElementTest#test} method.
+ *
+ * @param {String} html - HTML that should be in the document for the test
+ * @param {Object} assetMetadata - a JSON object describing where the bundles are.  This is needed to allow JSDOM to load the custom
+ * elements as if it were served up by a webserver
+ * @param {String} publicRoot - The root to where JS files.  When using this in a BrutRB web app, this would be where your bundled
+ * files are placed for serving.
+ *
+ * @see module:testing~CustomElementTest
+ */
+const createTestBasedOnHTML = ({html,assetMetadata,publicRoot}) => {
+  return new CustomElementTest(html,null,new AssetMetadata(assetMetadata,publicRoot))
+}
+
+export {
+  createTestBasedOnHTML
+}

data/brutrb.com/.vitepress/config.mjs

@@ -0,0 +1,106 @@
+import { defineConfig } from 'vitepress'
+import rdocLinker from './plugins/rdocLinker'
+import jsdocLinker from './plugins/jsdocLinker'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Brut RB",
+  description: "Documentation for the Brut.RB web framework.",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    search: {
+      provider: 'local',
+    },
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Getting Started', link: '/getting-started' },
+      { text: 'Overview', link: '/overview' },
+      { text: 'Brut API', link: '/api/index.html', target: "_self" },
+      { text: 'BrutJS', link: '/brut-js/api/index.html', target: "_self" },
+      { text: 'BrutCSS', link: '/brut-css/index.html', target: "_self" },
+    ],
+    outline: [ 2, 3] ,
+    sidebar: [
+      {
+        text: "Overview",
+        collapsed: false,
+        items: [
+          { text: "Getting Started", link: "/getting-started" },
+          { text: "Concepts", link: "/overview" },
+          { text: "Documentation Conventions", link: "/doc-conventions" },
+          { text: "Tutorial", link: "/tutorial" },
+          { text: "Dev Environment", link: "/dev-environment" },
+          { text: "AI Declaration", link: "/ai" },
+        ]
+      },
+      {
+        text: "Front-End",
+        collapsed: false,
+        items: [
+          { text: "Routes", link: "/routes" },
+          { text: "Pages", link: "/pages" },
+          { text: "Forms", link: "/forms" },
+          { text: "Handlers and Actions", link: "/handlers" },
+          { text: "Components", link: "/components" },
+          { text: "Flash and Session", link: "/flash-and-session" },
+          { text: "Space/Time Continuum", link: "/space-time-continuum" },
+          { text: "JavaScript", link: "/javascript" },
+          { text: "CSS", link: "/css" },
+          { text: "Assets", link: "/assets" },
+          { text: "BrutJS", link: "/brut-js" },
+        ]
+      },
+      {
+        text: "Back-End",
+        collapsed: false,
+        items: [
+          { text: "Database Schema", link: "/database-schema" },
+          { text: "Database Access", link: "/database-access" },
+          { text: "Seed Data", link: "/seed-data" },
+          { text: "Jobs", link: "/jobs" },
+          { text: "Business Logic", link: "/business-logic" },
+        ]
+      },
+      {
+        text: "Framework",
+        collapsed: false,
+        items: [
+          { text: "Configuration", link: "/configuration" },
+          { text: "Keyword Injection", link: "/keyword-injection" },
+          { text: "I18n", link: "/i18n" },
+          { text: "CLI / Tasks", link: "/cli" },
+          { text: "Deployment", link: "/deployment" },
+        ]
+      },
+      {
+        text: "Testing",
+        collapsed: false,
+        items: [
+          { text: "Unit Tests", link: "/unit-tests" },
+          { text: "End-to-End Tests", link: "/end-to-end-tests" },
+          { text: "Testing Custom Elements", link: "/custom-element-tests" },
+        ]
+      },
+      {
+        text: "Advanced Topics",
+        collapsed: false,
+        items: [
+          { text: "Route Hooks", link: "/hooks" },
+          { text: "Middleware", link: "/middleware" },
+          { text: "Instrumentation", link: "/instrumentation" },
+          { text: "Security", link: "/security" },
+        ],
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/thirdtank/brut' }
+    ]
+  },
+  markdown: {
+    config(md) {
+      md.use(rdocLinker)
+      md.use(jsdocLinker)
+    }
+  }
+})

data/brutrb.com/.vitepress/plugins/jsdocLinker.js

@@ -0,0 +1,34 @@
+export default function jsdocLinker(md) {
+
+  const orig = md.renderer.rules.code_inline || function(tokens, idx, options, env, self) {
+    return self.renderToken(tokens, idx, options);
+  };
+
+  function toPageName(tag) {
+    if (tag == "cv") {
+      return "ConstraintViolationMessage"
+    }
+    else if (tag == "cv-messages") {
+      return "ConstraintViolationMessages"
+    }
+    else {
+      return tag
+        .split('-')
+        .map(s => s.charAt(0).toUpperCase() + s.slice(1))
+        .join('');
+    }
+  }
+
+  md.renderer.rules.code_inline = function(tokens, idx, options, env, self) {
+    const content = tokens[idx].content;
+    // If it matches a custom element pattern
+    const match = content.match(/^<brut-([a-z][a-z0-9\-]*)>$/);
+    if (match) {
+      const tag = match[1];
+      const pageName = toPageName(tag);
+      return `<a href="/brut-js/api/${pageName}.html" target="_self" rel="noopener" data-no-router><code style="white-space: nowrap">&lt;brut-${tag}&gt;</code></a>`;
+    }
+    // ...your existing Ruby class matcher, if you want both!
+    return orig(tokens, idx, options, env, self);
+  };
+};

data/brutrb.com/.vitepress/plugins/rdocLinker.js

@@ -0,0 +1,18 @@
+export default function rdocLinker(md) {
+
+  const orig = md.renderer.rules.code_inline || function(tokens, idx, options, env, self) {
+    return self.renderToken(tokens, idx, options);
+  };
+
+  md.renderer.rules.code_inline = function(tokens, idx, options, env, self) {
+    const content = tokens[idx].content;
+    // Only match Ruby class-like tokens
+    if (/^Brut::[A-Z][A-Za-z0-9_:]+$/.test(content)) {
+      const path = content.replace(/::/g, '/')
+      return `<a href="/api/${path}.html" target="_self" rel="noopener" data-no-router><code>${md.utils.escapeHtml(content)}</code></a>`;
+    }
+    // Fallback to regular rendering
+    return orig(tokens, idx, options, env, self);
+  };
+
+};

data/brutrb.com/.vitepress/theme/custom.css

@@ -0,0 +1,7 @@
+:root {
+  --vp-font-family-base: 'Helvetica Neue', 'Nimbus Sans', sans-serif;
+  --vp-font-family-mono: Courier, monospace;
+}
+.image-bg {
+  display: none;
+}

data/brutrb.com/.vitepress/theme/index.js

@@ -0,0 +1,18 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from 'vue'
+import DefaultTheme from 'vitepress/theme-without-fonts'
+import './style.css'
+import './custom.css'
+
+/** @type {import('vitepress').Theme} */
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // https://vitepress.dev/guide/extending-default-theme#layout-slots
+    })
+  },
+  enhanceApp({ app, router, siteData }) {
+    // ...
+  }
+}