brut 0.0.20 → 0.0.22

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

@@ -0,0 +1,185 @@
+import Property         from "./Property.js"
+import PropertyCategory from "./PropertyCategory.js"
+import PropertyGroup    from "./PropertyGroup.js"
+import Rule             from "./Rule.js"
+import RuleCategory     from "./RuleCategory.js"
+import RuleGroup        from "./RuleGroup.js"
+import selectorParser   from "postcss-selector-parser"
+
+class Selectors {
+  constructor(selectorString) {
+    this.selectors = [];
+
+    selectorParser(selectorsAST => {
+      selectorsAST.each(selector => {
+        let trimmedSelector = selector.toString().trim()
+        if (trimmedSelector.endsWith(" *")) {
+          trimmedSelector = trimmedSelector.slice(0, -2).trim()
+        }
+        this.selectors.push(trimmedSelector)
+      });
+    }).processSync(selectorString)
+  }
+  forEach(callback) {
+    this.selectors.forEach(callback)
+  }
+}
+
+class DocState {
+  constructor(root) {
+    this.root = root
+    this.comment = null
+    this.propertyCategories = []
+    this.classCategories = []
+    this.insidePropertiesSection = false
+    this.insideRulesSection = false
+    this.refs = {}
+  }
+
+  get insideProperties() {
+    return this.insidePropertiesSection
+  }
+
+  set insideProperties(value) {
+    this.insidePropertiesSection = value
+    if (!value) {
+      if (this.currentCategory) {
+        this.propertyCategories.push(this.currentCategory)
+      }
+      this.currentCategory = null
+      this.currentScale = null
+    }
+  }
+
+  get insideRules() {
+    return this.insideRulesSection
+  }
+
+  set insideRules(value) {
+    if (value && this.insideProperties) {
+      this.insideProperties = false
+    }
+    this.insideRulesSection = value
+  }
+
+  newCategory(parsedComment) {
+    if (this.insideProperties) {
+      if (this.currentCategory) {
+        this.propertyCategories.push(this.currentCategory)
+      }
+      this.currentCategory = new PropertyCategory({
+        name: parsedComment.category[0],
+        explicitTitle: parsedComment.category[1],
+        description: parsedComment.description,
+        sees: parsedComment.sees,
+      })
+    }
+    else {
+      this.insideRules = true
+      if (this.currentCategory) {
+        this.classCategories.push(this.currentCategory)
+      }
+      this.currentCategory = new RuleCategory({
+        name: parsedComment.category[0],
+        explicitTitle: parsedComment.category[1],
+        description: parsedComment.description,
+        sees: parsedComment.sees,
+      })
+    }
+    this.refs[this.currentCategory.ref] = this.currentCategory
+    this.insideCategory = true
+    this.insideScale = false
+  }
+
+  newScale(parsedComment) {
+    if (this.insideProperties || this.insideRules) {
+      if (!this.currentCategory) {
+        throw this.root.error(`Something is wrong - no current category: ${parsedComment}`)
+      }
+      const groupAttributes = {
+        description: parsedComment.description,
+        sees: parsedComment.sees,
+      }
+      if (parsedComment.scale.length != 0) {
+        groupAttributes.name = parsedComment.scale[0]
+        groupAttributes.explicitTitle = parsedComment.scale[1]
+        groupAttributes.type = "scale"
+      }
+      else {
+        groupAttributes.name = parsedComment.group[0]
+        groupAttributes.explicitTitle = parsedComment.group[1]
+        groupAttributes.type = "group"
+      }
+      if (this.insideProperties) {
+        this.currentScale = new PropertyGroup(groupAttributes)
+      }
+      else if (this.insideRules) {
+        this.currentScale = new RuleGroup(groupAttributes)
+      }
+      this.refs[this.currentScale.ref] = this.currentScale
+      this.currentCategory.scales.push(this.currentScale)
+      this.insideScale = true
+    }
+    else {
+      throw this.root.error(`@scale may not be defined outside a @category`)
+    }
+  }
+
+  pushComment(parsedComment) {
+    if (this.insideScale) {
+      this.comment = parsedComment
+    }
+    else if (this.insideCategory) {
+      throw this.root.error(`Inside a category, the next comment must establish a scale`)
+    }
+    else {
+      throw this.root.error(`While parsing comments from @property definitions, encountered a comment without an @category. The comments inside the @property blocks must begin with a comment with the @category tag: ${parsedComment.normalizedComment}`)
+    }
+  }
+  pushProperty(node) {
+    let initialValue = null
+    let syntax = null
+    node.walkDecls(decl => {
+      if (decl.prop === 'initial-value') {
+        initialValue = decl.value
+      }
+      if (decl.prop === 'syntax') {
+        syntax = decl.value
+      }
+    })
+
+    const property = new Property({
+      name: node.params.trim(),
+      value: initialValue,
+      type: syntax,
+      description: this.comment ? this.comment.description : null,
+      sees: this.comment ? this.comment.sees : null,
+    })
+    this.currentScale.properties.push(property)
+    this.refs[property.ref] = property
+    this.commentStack = null
+  }
+  pushRule(node) {
+    const selectors = new Selectors(node.selector)
+    selectors.forEach( (selector) => {
+      const rule = new Rule({
+        selector: selector,
+        description: this.comment ? this.comment.description : null,
+        examples: this.comment ? this.comment.examples : [],
+        sees: this.comment ? this.comment.sees : null,
+        code: node.toString(),
+      })
+      this.currentScale.rules.push(rule)
+      this.refs[rule.ref] = rule
+    })
+    this.comment = null
+  }
+  done() {
+    if (this.currentCategory) {
+      this.classCategories.push(this.currentCategory)
+      this.currentCategory = null
+    }
+  }
+}
+
+export default DocState

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

@@ -0,0 +1,8 @@
+export default class Documentable {
+  constructor({name, description, sees, explicitTitle}) {
+    this.name          = name
+    this.description   = description
+    this.sees          = sees || []
+    this.explicitTitle = explicitTitle
+  }
+}

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

@@ -0,0 +1,7 @@
+import Documentable from "./Documentable.js"
+export default class Group extends Documentable {
+  constructor({name, description, type, sees, explicitTitle}) {
+    super({name, description, sees, explicitTitle})
+    this.type = type
+  }
+}

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

@@ -0,0 +1,73 @@
+import { parse as commentParser } from "comment-parser"
+import SeeRef from "./SeeRef.js"
+import SeeURL from "./SeeURL.js"
+
+class ParsedComment {
+  constructor(text) {
+    const trimmed = (text || "").trim()
+    const delimitersRemoved = trimmed.replace(/\/\*+/,"").replace(/\*+\//,"")
+    this.normalizedComment = `/**\n ${delimitersRemoved}\n*/`
+    this.parsedComment = commentParser(this.normalizedComment)
+    if (this.parsedComment.length == 0) {
+      throw `Was not given an actual comment: ${text}`
+    }
+    if (this.parsedComment.length > 1) {
+      throw `Something is wrong: Got more than one comment from ${text}`
+    }
+    this.parsedComment = this.parsedComment[0]
+  }
+
+  get description() {
+    return this.parsedComment.description
+  }
+
+  get isCategory() {
+    return this.category.length > 0
+  }
+
+  get category() {
+    const tags = this.parsedComment.tags
+    const categoryTag = tags.find(tag => tag.tag === 'category')
+    return categoryTag ? [ categoryTag.name, categoryTag.description ] : []
+  }
+
+  get isScaleOrGroup() {
+    return this.scale.length > 0 || this.group.length > 0
+  }
+
+  get scale() {
+    const tags = this.parsedComment.tags
+    const scaleTag = tags.find(tag => tag.tag === 'scale')
+    return scaleTag ? [ scaleTag.name, scaleTag.description ] : []
+  }
+
+  get group() {
+    const tags = this.parsedComment.tags
+    const groupTag = tags.find(tag => tag.tag === 'group')
+    return groupTag ? [ groupTag.name, groupTag.description ] : []
+  }
+
+  get examples() {
+    const tags = this.parsedComment.tags
+    const exampleTags = tags.filter(tag => tag.tag === 'example')
+    return exampleTags.map( (example) => {
+      return { name: example.name, code: example.source.map( (x) => x.tokens.description ) } 
+    })
+  }
+  get sees() {
+    const tags = this.parsedComment.tags
+    const seeTags = tags.filter(tag => tag.tag === 'see')
+    return seeTags.map( (see) => {
+      const ref = see.name
+      const url = see.description
+      if (!url) {
+        return new SeeRef(ref)
+      }
+      else {
+        return new SeeURL(ref, url)
+      }
+    })
+  }
+
+}
+export default ParsedComment

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

@@ -0,0 +1,9 @@
+import Documentable from "./Documentable.js"
+export default class Property extends Documentable {
+  constructor({name, value, type, description, sees}) {
+    super({name, description, sees})
+    this.ref = name
+    this.value = value
+    this.type = type
+  }
+}

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

@@ -0,0 +1,4 @@
+import Category from './Category.js'
+export default class PropertyCategory extends Category {
+  get ref() { return `property-category:${this.name}` }
+}

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

@@ -0,0 +1,8 @@
+import Group from "./Group.js"
+export default class PropertyGroup extends Group {
+  constructor({name, description, type, sees, explicitTitle}) {
+    super({name, description, type, sees, explicitTitle})
+    this.properties = []
+    this.ref = `property-${type}:${name}`
+  }
+}

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

@@ -0,0 +1,12 @@
+import Documentable from "./Documentable.js"
+
+export default class Rule extends Documentable {
+  constructor({selector, description, examples, code, sees}) {
+    super({name: selector.replace(/^\./, ''), description, sees})
+    this.selector = selector
+    this.ref = this.name
+    this.description = description
+    this.examples = examples
+    this.code = code
+  }
+}

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

@@ -0,0 +1,4 @@
+import Category from './Category.js'
+export default class RuleCategory extends Category {
+  get ref() { return `class-category:${this.name}` }
+}

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

@@ -0,0 +1,8 @@
+import Group from "./Group.js"
+export default class RuleGroup extends Group {
+  constructor({name, description, type, sees, explicitTitle}) {
+    super({name, description, type, sees, explicitTitle})
+    this.rules = []
+    this.ref = `class-${type}:${name}`
+  }
+}

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

@@ -0,0 +1,5 @@
+export default class SeeRef {
+  constructor(ref) {
+    this.ref = ref
+  }
+}

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

@@ -0,0 +1,9 @@
+export default class SeeURL {
+  constructor(linkText, url) {
+    this.linkText = linkText
+    this.url      = url
+  }
+
+  get ref() { return null }
+
+}

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

@@ -0,0 +1,49 @@
+import ParsedComment from "./generateDocumentationPlugin/ParsedComment.js"
+import DocState from "./generateDocumentationPlugin/DocState.js"
+
+const generateDocumentationPlugin = (parsedDocumentation) => {
+  return {
+    postcssPlugin: 'generate-documentation',
+    Once(root) {
+      let state = new DocState(root)
+      state.insideProperties = true // Assume @property values preceed all others
+      root.walk(node => {
+        if (node.type === 'comment') {
+          const parsedComment = new ParsedComment(node.text)
+          if (parsedComment.isCategory) {
+            state.newCategory(parsedComment)
+          }
+          else if ( parsedComment.isScaleOrGroup ) {
+            state.newScale(parsedComment)
+          }
+          else {
+            state.pushComment(parsedComment)
+          }
+        }
+
+        else if (node.type === 'atrule' && node.name === 'property') {
+          state.pushProperty(node)
+        }
+
+        else if (node.type === 'rule' && node.selector === ':root') {
+          state.insideProperties = false
+        }
+
+        else if (node.type === 'rule') {
+          state.insideRules = true
+          state.pushRule(node)
+        }
+        else {
+        }
+      })
+      state.done()
+      parsedDocumentation.propertyCategories = state.propertyCategories
+      parsedDocumentation.classCategories = state.classCategories.filter( (category) => {
+        return category.name != "reset"
+      })
+      parsedDocumentation.refs = state.refs
+    }
+  }
+}
+generateDocumentationPlugin.postcss = true
+export default generateDocumentationPlugin

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

@@ -0,0 +1,45 @@
+import postcss from "postcss"
+import Logger  from "../Logger.js"
+
+const generateRootCustomPropertiesPlugin = () => {
+  return {
+    postcssPlugin: 'generate-root-properties',
+    Once(root) {
+      const rootVars = []
+      let lastAtProperty = null
+      root.walkAtRules("property", (atRule) => {
+        const name = atRule.params.trim()
+        let initialValue = null
+
+        lastAtProperty = atRule
+
+        atRule.walkDecls(decl => {
+          if (decl.prop === 'initial-value') {
+            initialValue = decl.value
+          }
+        })
+
+        if (initialValue) {
+          const decl = postcss.decl({ prop: name, value: initialValue })
+          rootVars.push(decl)
+        }
+        else {
+          Logger.warn(`No initial-value found for @property ${name}`)
+        }
+
+      })
+      if (rootVars.length > 0) {
+        const rootRule = postcss.rule({ selector: ':root' })
+        rootVars.forEach(decl => rootRule.append(decl))
+        if (lastAtProperty) {
+          lastAtProperty.after(rootRule)
+        }
+        else {
+          root.append(rootRule)
+        }
+      }
+    }
+  }
+}
+generateRootCustomPropertiesPlugin.postcss = true
+export default generateRootCustomPropertiesPlugin

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

@@ -0,0 +1,145 @@
+import fs        from "node:fs"
+import postcss   from "postcss"
+import Logger    from "./Logger.js"
+
+class PseudoClass {
+  constructor(pseudoClass, prefix, extra, classRules) {
+    this.pseudoClass = pseudoClass
+    this.prefix      = prefix
+    this.extra       = extra
+    this.classRules  = classRules
+    this.error       = null
+    this.rule        = null
+  }
+  isError() { return false }
+
+  surroundAtRule() {
+    if ( (this.pseudoClass == "hover") && (this.extra == "true") ) {
+      return { name: "media", params: "(hover: hover)" }
+    }
+    return null
+  }
+  includesSelector(selector) {
+    if (this.#exactlyOneDot(selector)) {
+      return this.classRules.some( (classRule) => classRule.includesSelector(selector) )
+    }
+    else {
+      return false
+    }
+  }
+
+  #exactlyOneDot(selector) {
+    return selector.startsWith(".") && (selector.lastIndexOf(".") == 0) && selector.indexOf(" ") == -1
+  }
+}
+class ParseError {
+  constructor(rule, error) {
+    this.rule  = rule
+    this.error = error
+  }
+  isError() { return true }
+}
+
+class ColorsClassRule {
+  static COLORS = [
+    "red",
+    "orange",
+    "yellow",
+    "green",
+    "blue",
+    "purple",
+    "gray",
+    "black",
+    "white",
+  ]
+
+  includesSelector(selector) {
+    return ColorsClassRule.COLORS.some( (color) => selector.startsWith(`.${color}-`) )
+  }
+}
+
+class PrefixedClassRule {
+  constructor(prefix) {
+    this.prefix = prefix
+  }
+  includesSelector(selector) {
+    return selector.startsWith(`.${this.prefix}`)
+  }
+}
+class SpecificClassRule {
+  constructor(className) {
+    this.selector = `.${className}`
+  }
+  includesSelector(selector) {
+    return selector === this.selector
+  }
+}
+
+class AtRuleParenExpression {
+  constructor(params) {
+    this.value = params.trim().replace(/^\(\s*/,"").replace(/\s*\)$/,"")
+  }
+  isEmpty() {
+    return this.value.length == 0
+  }
+}
+
+const pseudoClassConfigParser = (pseudoClassConfigFile) => {
+  const pseudoClasses = [
+  ]
+
+  if (!pseudoClassConfigFile) {
+    return pseudoClasses
+  }
+
+  const css = fs.readFileSync(pseudoClassConfigFile, 'utf8')
+  const parsedCSS = postcss.parse(css, { from: pseudoClassConfigFile })
+
+  parsedCSS.walkAtRules("brut-pseudo", (rule) => {
+    const [pseudoClass,prefix,extra] = new AtRuleParenExpression(rule.params).value.split(/\s+/)
+    if (!pseudoClass) {
+      pseudoClasses.push(new ParseError(rule, "@brut-pseudo requires an '(-expression)' of pseudo-class and prefix"))
+    }
+    else if (!prefix) {
+      pseudoClasses.push(new ParseError(rule, "@brut-pseudo found a pseudo-class, but no prefix"))
+    }
+    else {
+      const classRules = []
+      rule.walkAtRules( (innerRule) => {
+        if (innerRule.name == "brut-class") {
+          const params = new AtRuleParenExpression(innerRule.params)
+          if (params.isEmpty()) {
+            pseudoClasses.push(new ParseError(rule, "@brut-class must contain a CSS class name"))
+          }
+          else {
+            classRules.push(new SpecificClassRule(params.value))
+          }
+        }
+        else if (innerRule.name == "brut-classes-with-prefix") {
+          const params = new AtRuleParenExpression(innerRule.params)
+          if (params.isEmpty()) {
+            pseudoClasses.push(new ParseError(rule, "@brut-classes-with-prefix must contain a CSS class name prefix"))
+          }
+          else {
+            classRules.push(new PrefixedClassRule(params.value))
+          }
+        }
+        else if (innerRule.name == "brut-colors") {
+          classRules.push(new ColorsClassRule())
+        }
+        else {
+          Logger.warn(":@brut-pseudo contains an unknown at-rule", innerRule.name, "ignoring it")
+        }
+      })
+      if (classRules.length == 0) {
+        pseudoClasses.push(new ParseError(rule, "@brut-pseudo requires at least one @brut-class, @brut-classes-with-prefix or @brut-colors rule"))
+      }
+      else {
+        pseudoClasses.push(new PseudoClass(pseudoClass, prefix, extra, classRules))
+      }
+    }
+  })
+  return pseudoClasses
+}
+
+export default pseudoClassConfigParser

data/brut-js/.projections.json

@@ -0,0 +1,10 @@
+{
+  "src/*.js": {
+    "alternate": "specs/{}.spec.js",
+    "type": "source"
+  },
+  "specs/*.spec.js": {
+    "alternate": "src/{}.js",
+    "type": "spec"
+  }
+}