brut 0.17.0 → 0.18.0

data/brut-css/src/js/docGenerator.js

@@ -1,467 +0,0 @@
-import ejs        from "ejs"
-import fs         from "node:fs"
-import path       from "node:path"
-import markdownit from "markdown-it"
-import Prism      from "prismjs"
-import beautify   from "js-beautify"
-import Logger     from "./Logger.js"
-
-import loadLanguages from "prismjs/components/index.js"
-loadLanguages(["html"])
-
-/** A title has a string usable as a human-readable title, plus a sort key used
- * to sort pages by their title
- */
-class Title {
-  /** Create a title based on a directory name that may have a prefix used for sorring */
-  static fromDirName(dirName) {
-    const nameWithoutPrefix = dirName.replace(/^\d+_/, '').replace(/\..*$/,'')
-    const title = nameWithoutPrefix.
-      split('-').
-      map(word => word.charAt(0).toUpperCase() + word.slice(1)).
-      join(' ')
-    return new this(title, dirName)
-  }
-  constructor(title, sortKey) {
-    this.title = title
-    this.sortKey = sortKey
-  }
-  toString() { return this.title }
-  static compare(a,b) {
-    if (!a.title) { throw `${a.constructor.name} has no title` }
-    if (!b.title) { throw `${b.constructor.name} has no title` }
-    if (!a.title.sortKey) { throw `${a.constructor.name} has a title, but it's not a Title` }
-    if (!b.title.sortKey) { throw `${b.constructor.name} has a title, but it's not a Title` }
-    return a.title.sortKey.localeCompare(b.title.sortKey)
-  }
-}
-
-/* A page to generate based on a template */
-class Page {
-  constructor(pathToPageTemplate, pathToPageOutput) {
-    this.pathToPageTemplate = pathToPageTemplate
-    this.uri = pathToPageOutput
-  }
-
-  static compare(a,b) {
-    Title.compare(a.page, b.page)
-  }
-}
-
-/* A static file that isn't being run through EJS */
-class StaticFile extends Page {
-  get title() {
-    return Title.fromDirName(path.basename(this.pathToPageTemplate))
-  }
-  generate(outputDirName) {
-    Logger.info("Copying %s from %s", this.uri, this.pathToPageTemplate)
-    fs.copyFileSync(this.pathToPageTemplate, path.join(outputDirName, this.uri))
-  }
-}
-
-/* A templated page that will be run through EJS */
-class TemplatePage extends Page {
-  constructor(pathToPageTemplate, pathToPageOutput, pathToPageContent) {
-    super(pathToPageTemplate, pathToPageOutput)
-    this.pathToPageContent = pathToPageContent
-  }
-  get title() {
-    return Title.fromDirName(path.basename(this.pathToPageContent))
-  }
-  generate(outputDirName, pathToBrutCSSRoot, nav) {
-    Logger.info("Generating %s from %s using %s", this.uri, this.pathToPageTemplate, this.pathToPageContent || "no additional content")
-    let htmlContent = null
-    if (this.pathToPageContent) {
-      const contents = fs.readFileSync(this.pathToPageContent, "utf8")
-      if (path.extname(this.pathToPageContent) === ".md") {
-        const markdown = new markdownit({
-          html: true,
-          linkify: true,
-          typographer: true,
-        })
-        htmlContent = markdown.render(contents)
-      }
-      else if (path.extname(this.pathToPageContent) === ".html") {
-        htmlContent = contents
-      }
-      else {
-        throw `Unsupported file type for ${this.pathToPageContent}. Only .md and .html are supported.`
-      }
-    }
-    const html = ejs.render(fs.readFileSync(this.pathToPageTemplate, "utf8"), {
-      nav:nav,
-      pathToBrutCSSRoot: pathToBrutCSSRoot,
-      content: htmlContent || ""
-    }, {
-      filename: this.pathToPageTemplate
-    })
-    const destinationFile = path.join(outputDirName, this.uri)
-    fs.mkdirSync(path.dirname(destinationFile), { recursive: true })
-    fs.writeFileSync(destinationFile, html, "utf8")
-    Logger.info("Wrote %s", destinationFile)
-  }
-}
-
-/* The page used for a category of custom properties */
-class PropertiesPage extends TemplatePage {
-  constructor(pathToPageContent, pathToPageOutput, category, parsedDocumentation) {
-    super(pathToPageContent, pathToPageOutput)
-    Logger.debug("Creating PropertiesPage %s for %s", pathToPageContent, category.name)
-    this.category = category
-    this.colorsCategory  = parsedDocumentation.classCategories.find( (category) => category.ref == "class-category:foreground-colors" )
-  }
-  get documentationRef() { return this.category.ref }
-  get title() { return Title.fromDirName(this.category.name) }
-  generate(outputDirName, pathToBrutCSSRoot, nav) {
-    const locals = {
-      nav:nav,
-      pathToBrutCSSRoot: pathToBrutCSSRoot,
-      category: this.category,
-    }
-    if ( (this.category.ref == "class-category:foreground-colors") ||
-         (this.category.ref == "class-category:background-colors") ||
-         (this.category.ref == "class-category:border-colors") ) {
-      locals.colorsCategory = this.colorsCategory
-    }
-
-    const html = ejs.render(fs.readFileSync(this.pathToPageTemplate, "utf8"),
-      locals,
-      {
-        filename: this.pathToPageTemplate
-      })
-    const destinationFile = path.join(outputDirName, this.uri)
-    fs.mkdirSync(path.dirname(destinationFile), { recursive: true })
-    fs.writeFileSync(destinationFile, html, "utf8")
-    Logger.debug("Wrote %s", destinationFile)
-  }
-}
-
-/* The page used for a category of CSS classe */
-class ClassesPage extends PropertiesPage {
-}
-
-/* A section of the nav, which is a title and a bunch of pages it links to */
-class NavSection {
-  static fromPath(sourcePath, parsedDocumentation) {
-    const basename = path.basename(sourcePath)
-    if (basename.match(/^\d+_properties$/)) {
-      return new PropertiesSection(sourcePath, parsedDocumentation)
-    }
-    if (basename.match(/^\d+_classes/)) {
-      return new ClassesSection(sourcePath, parsedDocumentation)
-    }
-    return new StaticPagesSection(sourcePath)
-  }
-}
-
-/* The section of the nav for custom properties */
-class PropertiesSection extends NavSection {
-  constructor(sourcePath, parsedDocumentation) {
-    super()
-    this.categoryTemplate = path.join(sourcePath, "page.html.ejs")
-    if (!fs.existsSync(this.categoryTemplate)) {
-      throw `No category template found at ${this.categoryTemplate}`
-    }
-    this.parsedDocumentation = parsedDocumentation
-    const basename = path.basename(sourcePath)
-    this.uriBase = basename.replace(/^\d+_/,"")
-    this.title = Title.fromDirName(basename)
-  }
-  get items() {
-    return this.parsedDocumentation.propertyCategories.map( (category) => {
-      return {
-        page: new PropertiesPage(
-          this.categoryTemplate,
-          path.join(this.uriBase, category.name) + ".html",
-          category,
-          this.parsedDocumentation,
-        )
-      }
-    })
-  }
-}
-
-/* The section of the nav for CSS classes */
-class ClassesSection extends PropertiesSection {
-
-  get items() {
-    return this.parsedDocumentation.classCategories.map( (category) => {
-      return {
-        page: new ClassesPage(
-          this.categoryTemplate,
-          path.join(this.uriBase, category.name) + ".html",
-          category,
-          this.parsedDocumentation)
-      }
-    })
-  }
-}
-
-/* A section of static pages not based on API docs, but that will be run through EJS */
-class StaticPagesSection extends NavSection {
-  constructor(sourcePath) {
-    super()
-    this.sourcePath = sourcePath
-    this.pageTemplate = path.join(sourcePath, "page.html.ejs")
-    if (!fs.existsSync(this.pageTemplate)) {
-      throw `No category template found at ${this.pageTemplate}`
-    }
-
-    const basename = path.basename(sourcePath)
-    this.title = Title.fromDirName(basename)
-
-    this.items = []
-
-    fs.readdirSync(sourcePath).forEach((file) => {
-      const fullPath = path.join(sourcePath, file)
-      const stat = fs.statSync(fullPath)
-      if (stat.isDirectory()) {
-        throw `${fullPath} is a directroy. ${sourcePath} may only includes files`
-      }
-      if (file != "page.html.ejs") {
-        const pathToPageOutput = path.join(
-          ...path.join(basename, file).split(path.sep).map( (part) => {
-            return part.replace(/^\d+_/,"").replace(/\..*$/,".html")
-          })
-        )
-        this.items.push({
-          page: new TemplatePage(this.pageTemplate, pathToPageOutput, fullPath)
-        })
-      }
-    })
-    this.items.sort(Page.compare)
-  }
-}
-
-/* Given the description parsed from the source, this expands it to HTML and also
- * locates all cross-references.
- */
-class ExpandedDescription {
-  constructor(documentedEntry, documentationRefs, pathToBrutCSSRoot) {
-    const unexpandedDescription = documentedEntry.description || ""
-
-    this.doc = unexpandedDescription.replace(/\{([^}]+)\}/g, (_, key) => {
-      const reference = key.trim()
-      let referenced = documentationRefs.refs[reference]
-      if (!referenced) {
-        throw new Error(`Could not find reference to ${reference} in documentation`)
-      }
-      return `[${referenced.title}](${pathToBrutCSSRoot}/${referenced.uri})`
-    })
-  }
-  toHTML() {
-    const markdown = new markdownit({
-      html: true,
-      linkify: true,
-      typographer: true,
-    })
-    return markdown.render(this.doc)
-  }
-}
-class ExpandedSee {
-  constructor(see, documentationRefs, pathToBrutCSSRoot) {
-    if (see.ref) {
-      let referenced = documentationRefs.refs[see.ref]
-      if (!referenced) {
-        const [part,rest] = see.ref.split(":",2)
-        const candidates = Object.keys(documentationRefs).filter( (key) => key.startsWith(part) )
-        throw new Error(`Could not find reference to ${see.ref} in documentation ${ candidates }`)
-      }
-      this.doc = `[${referenced.title}](${pathToBrutCSSRoot}/${referenced.uri})`
-    }
-    else {
-      this.doc = `[${see.linkText}](${see.url}) (external)`
-    }
-  }
-  toHTML() {
-    const markdown = new markdownit({
-      html: true,
-      linkify: true,
-      typographer: true,
-    })
-    return markdown.render(this.doc)
-  }
-}
-
-class Documentation {
-  constructor(templateRootDirName, parsedDocumentation, pathToBrutCSSRoot) {
-    const nav = []
-    const pages = []
-    fs.readdirSync(templateRootDirName).forEach((file) => {
-      const fullPath = path.join(templateRootDirName, file)
-      const stat = fs.statSync(fullPath)
-      if (stat.isDirectory()) {
-        if (file != "includes") {
-          nav.push(NavSection.fromPath(fullPath, parsedDocumentation))
-        }
-      }
-      else {
-        if (this.#isEJS(file)) {
-          pages.push(new TemplatePage(
-            fullPath,
-            file.replace(/^\d+_/,"").replace(/\..*$/,".html")
-          ))
-        }
-        else {
-          pages.push(new StaticFile(
-            fullPath,
-            file
-          ))
-        }
-      }
-    })
-    nav.sort(Title.compare)
-    this.nav = nav
-    this.pages = pages
-    this.#decorate(parsedDocumentation, pathToBrutCSSRoot)
-  }
-
-  #isEJS(file) {
-    return path.extname(file) === ".ejs"
-  }
-
-  #decorate(parsedDocumentation, pathToBrutCSSRoot) {
-    this.#addTitles(parsedDocumentation)
-    this.#expandReferences(parsedDocumentation, pathToBrutCSSRoot)
-    this.#highlightCode(parsedDocumentation)
-  }
-
-  #highlightCode(parsedDocumentation) {
-    parsedDocumentation.classCategories.forEach( (category) => {
-      category.scales.forEach( (scale) => {
-        scale.rules.forEach( (rule) => {
-          rule.highlightedCode = Prism.highlight(
-            rule.code,
-            Prism.languages.css,
-            "css"
-          )
-          rule.examples.forEach( (example) => {
-            const prettyHTML = beautify.html(example.code.join("\n"), {
-              wrap_line_length: 60,
-              indent_size: 2,
-            })
-            example.highlightedCode = Prism.highlight(
-              prettyHTML,
-              Prism.languages.html,
-              "html"
-            )
-          })
-        })
-      })
-    })
-  }
-
-  #expandReferences(parsedDocumentation, pathToBrutCSSRoot) {
-    const referencedDocumentation = new ReferencedDocumentation(this)
-    parsedDocumentation.propertyCategories.forEach( (category) => {
-      category.descriptionHTML = (new ExpandedDescription(category, referencedDocumentation, pathToBrutCSSRoot)).toHTML()
-      category.seeLinks = category.sees.map( (see) => (new ExpandedSee(see, referencedDocumentation, pathToBrutCSSRoot)).toHTML() )
-      category.scales.forEach( (scale) => {
-        scale.descriptionHTML = (new ExpandedDescription(scale, referencedDocumentation, pathToBrutCSSRoot)).toHTML()
-        scale.seeLinks = scale.sees.map( (see) => (new ExpandedSee(see, referencedDocumentation, pathToBrutCSSRoot)).toHTML() )
-        if (!scale.name) {
-          throw new Error(`Scale ${scale.ref}.${scale.constructor.name} has no name`)
-        }
-        scale.properties.forEach( (property) => {
-          property.descriptionHTML = (new ExpandedDescription(property, referencedDocumentation, pathToBrutCSSRoot)).toHTML()
-          property.seeLinks = property.sees.map( (see) => (new ExpandedSee(see, referencedDocumentation, pathToBrutCSSRoot)).toHTML() )
-        })
-      })
-    })
-    parsedDocumentation.classCategories.forEach( (category) => {
-      category.descriptionHTML = (new ExpandedDescription(category, referencedDocumentation, pathToBrutCSSRoot)).toHTML()
-      category.seeLinks = category.sees.map( (see) => (new ExpandedSee(see, referencedDocumentation, pathToBrutCSSRoot)).toHTML() )
-      category.scales.forEach( (scale) => {
-        scale.descriptionHTML = (new ExpandedDescription(scale, referencedDocumentation, pathToBrutCSSRoot)).toHTML()
-        scale.seeLinks = scale.sees.map( (see) => (new ExpandedSee(see, referencedDocumentation, pathToBrutCSSRoot)).toHTML() )
-        scale.rules.forEach( (rule) => {
-          rule.descriptionHTML = (new ExpandedDescription(rule, referencedDocumentation, pathToBrutCSSRoot)).toHTML()
-          rule.seeLinks = rule.sees.map( (see) => (new ExpandedSee(see, referencedDocumentation, pathToBrutCSSRoot)).toHTML() )
-        })
-      })
-    })
-  }
-
-  #addTitles(parsedDocumentation) {
-    parsedDocumentation.propertyCategories.forEach( (category) => {
-      category.title = category.explicitTitle || category.name.split(/-/).map( (part) => {
-        return part.charAt(0).toUpperCase() + part.slice(1)
-      }).join(" ")
-      category.scales.forEach( (scale) => {
-        if (!scale.name) {
-          throw `Scale ${scale.ref}.${JSON.stringify(scale)} has no name`
-        }
-        scale.title = scale.explicitTitle || scale.name.split(/-/).map( (part) => {
-          return part.charAt(0).toUpperCase() + part.slice(1)
-        }).join(" ")
-      })
-    })
-    parsedDocumentation.classCategories.forEach( (category) => {
-      category.title = category.explicitTitle || category.name.split(/-/).map( (part) => {
-        return part.charAt(0).toUpperCase() + part.slice(1)
-      }).join(" ")
-      category.scales.forEach( (scale) => {
-        scale.title = scale.explicitTitle || scale.name.split(/-/).map( (part) => {
-          return part.charAt(0).toUpperCase() + part.slice(1)
-        }).join(" ")
-      })
-    })
-  }
-}
-
-class ReferencedDocumentation {
-  constructor(documentation) {
-    this.refs = {}
-    documentation.nav.forEach( (navSection) => {
-      navSection.items.forEach( ({page}) => {
-        if (page.documentationRef) {
-          this.refs[page.documentationRef] = page
-          if (page.category) {
-            page.category.scales.forEach( (scale) => {
-              this.refs[scale.ref] = {
-                title: new Title(scale.title, scale.name),
-                uri: page.uri + `#${scale.ref}`
-              }
-              if (scale.properties) {
-                scale.properties.forEach( (property) => {
-                  this.refs[property.ref] = {
-                    title: new Title("`" + property.name + "`", property.name),
-                    uri: page.uri + `#${property.ref}`
-                  }
-                })
-              }
-              else if (scale.rules) {
-                scale.rules.forEach( (rule) => {
-                  this.refs[rule.ref] = {
-                    title: new Title("`" + rule.selector + "`", rule.selector),
-                    uri: page.uri + `#${rule.ref}`
-                  }
-                })
-              }
-            })
-          }
-          else {
-            throw `No category for ${page.documentationRef} / ${page.constructor.name}`
-          }
-        }
-        else {
-          Logger.info("Skipping %s because it has no documentation reference", page.uri)
-        }
-      })
-    })
-  }
-}
-
-const docGenerator = (outputDirName, templateDirName, parsedDocumentation, pathToBrutCSSRoot) => {
-  const documentation = new Documentation(templateDirName, parsedDocumentation, pathToBrutCSSRoot)
-
-  documentation.pages.forEach( page => page.generate(outputDirName, pathToBrutCSSRoot, documentation.nav) )
-
-  documentation.nav.forEach( (navSection) => {
-    navSection.items.forEach( ({page}) => {
-      page.generate(outputDirName, pathToBrutCSSRoot, documentation.nav)
-    })
-  })
-}
-
-export default docGenerator

data/brut-css/src/js/mediaQueryConfigParser.js

@@ -1,98 +0,0 @@
-import fs        from "node:fs"
-import postcss   from "postcss"
-import { parse } from "comment-parser"
-
-class NormalizedCommentText {
-  constructor(text) {
-    const trimmed = (text || "").trim()
-    const delimitersRemoved = trimmed.replace(/\/\*+/,"").replace(/\*+\//,"")
-    this.normalizedComment = `/**\n ${delimitersRemoved}\n*/`
-  }
-}
-class MediaQuery {
-  constructor(rawQuery, documentation, suffix) {
-    this.rawQuery      = rawQuery
-    this.documentation = documentation
-    this.suffix        = suffix
-    this.error         = null
-  }
-
-  isError() { return false }
-}
-
-class ParseError {
-  constructor(rawQuery, error) {
-    this.rawQuery = rawQuery
-    this.error    = error
-  }
-  isError() { return true }
-}
-
-class CommentParsingError {
-  constructor(commentText, error) {
-    this.commentText = commentText
-    this.error       = error
-  }
-  isError() { return true }
-}
-class ParsedComment {
-  static fromNormalizedCommentText(normalizedCommentText) {
-    const commentParserResult = parse(normalizedCommentText.normalizedComment)
-    if (commentParserResult.length == 0) {
-      return new CommentParsingError(commentText, "Did not contain a preceding comment (which should contain a @suffix tag)")
-    }
-    if (commentParserResult.length > 1) {
-      throw `Something is wrong: Got more than one comment from ${normalizedCommentText.normalizedComment}`
-    }
-    const parsedComment = commentParserResult[0]
-    const suffixTags = parsedComment.tags.filter((tag) => tag.tag === "suffix")
-    if (suffixTags.length == 0) {
-      return new CommentParsingError(normalizedCommentText.normalizedComment, "Did not contain a @suffix tag")
-    }
-    if (suffixTags.length > 1) {
-      return new CommentParsingError(normalizedCommentText.normalizedComment, "Contained more than one @suffix tag")
-    }
-    return new ParsedComment(parsedComment.description, suffixTags[0].name)
-  }
-
-  constructor(documentation, suffix) {
-    this.documentation = documentation
-    this.suffix        = suffix
-    this.error         = null
-  }
-
-  isError() { return false }
-}
-
-const mediaQueryConfigParser = (mediaQueryConfigFile) => {
-  const mediaQueries = [
-    new MediaQuery(null, "The default media query", null)
-  ]
-  if (!mediaQueryConfigFile) {
-    return mediaQueries
-  }
-  const css = fs.readFileSync(mediaQueryConfigFile, 'utf8')
-  const parsedCSS = postcss.parse(css, { from: mediaQueryConfigFile })
-
-
-  parsedCSS.walkAtRules('media', (rule) => {
-    const mediaQuery = rule.params.trim()
-    const comment = rule.prev()
-
-    if (!comment || comment.type !== "comment") {
-      mediaQueries.push(new ParseError(mediaQuery, "Must be preceded by a comment"))
-    }
-    else {
-      const parsedComment = ParsedComment.fromNormalizedCommentText(new NormalizedCommentText(comment.text))
-      if (parsedComment.isError()) {
-        mediaQueries.push(new ParseError(mediaQuery, parsedComment.error))
-      }
-      else {
-        mediaQueries.push(new MediaQuery(mediaQuery, parsedComment.documentation, parsedComment.suffix))
-      }
-    }
-  })
-  return mediaQueries
-}
-
-export default mediaQueryConfigParser

data/brut-css/src/js/post-css-plugins/addMediaQueriesPlugin.js

@@ -1,49 +0,0 @@
-import postcss from "postcss"
-
-const addMediaQueriesPlugin = (mediaQueries) => {
-  return {
-    postcssPlugin: 'add-media-queries',
-    Once(root) {
-      const toAppend = []
-      mediaQueries.forEach( (mediaQuery) => {
-        const atRule = mediaQuery.rawQuery ? postcss.atRule({ name: "media", params: mediaQuery.rawQuery }) : null
-        root.walkRules( (rule) => {
-          if (rule.selector !== ":root") {
-            const cloned = rule.clone();
-            let changedSelectors = false
-            if (mediaQuery.suffix) {
-              cloned.selectors = cloned.selectors.map( (selector) => {
-                if ( selector.startsWith(".") && (selector.lastIndexOf(".") == 0) && selector.indexOf(" ") == -1 ) {
-                  changedSelectors = true
-                  if (selector.indexOf(":") == -1) {
-                    return selector + `-${mediaQuery.suffix}`
-                  }
-                  else {
-                    return selector.replace(/:(.*)$/, `-${mediaQuery.suffix}:$1`)
-                  }
-                }
-                else {
-                  return selector
-                }
-              })
-            }
-            if (atRule && changedSelectors) {
-              atRule.append(cloned)
-            }
-            else {
-              // No need to append - this rule is already there
-            }
-          }
-        })
-        if (atRule) {
-          toAppend.push(atRule)
-        }
-      })
-      toAppend.forEach( (rule) => {
-        root.append(rule)
-      })
-    }
-  }
-}
-addMediaQueriesPlugin.postcss = true
-export default addMediaQueriesPlugin

data/brut-css/src/js/post-css-plugins/addPseudoClassesPlugin.js

@@ -1,42 +0,0 @@
-import postcss from "postcss"
-
-const addPseudoClassesPlugin = (pseudoClasses) => {
-  return {
-    postcssPlugin: 'add-pseudo-classes',
-    Once(root) {
-      const toAppend = []
-      pseudoClasses.forEach( (pseudoClass) => {
-        const atRule = pseudoClass.surroundAtRule() ? postcss.atRule(pseudoClass.surroundAtRule()) : null
-        root.walkRules( (rule) => {
-          if (rule.selector !== ":root") {
-            if (pseudoClass.includesSelector(rule.selector)) {
-              const cloned = rule.clone();
-              cloned.selectors = cloned.selectors.map(sel => {
-                if (sel.startsWith(".")) {
-                  return `.${pseudoClass.prefix}-` + sel.slice(1) + `:${pseudoClass.pseudoClass}`
-                }
-                else {
-                  return sel
-                }
-              })
-              if (atRule) {
-                atRule.append(cloned)
-              }
-              else {
-                toAppend.push(cloned)
-              }
-            }
-          }
-        })
-        if (atRule) {
-          toAppend.push(atRule)
-        }
-      })
-      toAppend.forEach( (rule) => {
-        root.append(rule)
-      })
-    }
-  }
-}
-addPseudoClassesPlugin.postcss = true
-export default addPseudoClassesPlugin

data/brut-css/src/js/post-css-plugins/generateDocumentationPlugin/Category.js

@@ -1,9 +0,0 @@
-import Documentable from "./Documentable.js"
-
-class Category extends Documentable {
-  constructor({name, description, sees}) {
-    super({name, description, sees})
-    this.scales = []
-  }
-}
-export default Category