feat: Generisize StateGroup and State to Attribute and AttrValue.

Author: amiller-gh

packages/css-blocks/src/Block/State.ts packages/css-blocks/src/Block/AttrValue.ts

@@ -5,44 +5,43 @@ import {
 } from "@opticss/element-analysis";
 import { assertNever, assertNeverCalled } from "@opticss/util";
 
-import { UNIVERSAL_STATE } from "../BlockSyntax";
+import { UNIVERSAL_ATTR_VALUE } from "../BlockSyntax";
 import { OptionsReader } from "../OptionsReader";
 import { OutputMode } from "../OutputMode";
 
+import { Attribute } from "./Attribute";
 import { Block } from "./Block";
 import { BlockClass } from "./BlockClass";
 import { RulesetContainer } from "./RulesetContainer";
-import { StateGroup } from "./StateGroup";
 import { Style } from "./Style";
 
 /**
- * States represent a state attribute selector in a particular Block.
- * A State can have sub-states that are considered to be mutually exclusive.
- * States can be designated as "global";
+ * AttrValue represent the value of an Attribute in a particular Block.
+ * An Attribute can have AttrValue that are considered to be mutually exclusive.
+ * Attributes can be designated as "global";
  */
-export class State extends Style<State, Block, StateGroup, never> {
+export class AttrValue extends Style<AttrValue, Block, Attribute, never> {
   isGlobal = false;
 
   private _sourceAttributes: AttributeNS[] | undefined;
-  public readonly rulesets: RulesetContainer<State>;
+  public readonly rulesets: RulesetContainer<AttrValue>;
 
   /**
-   * State constructor. Provide a local name for this State, an optional group name,
+   * AttrValue constructor. Provide a local name for this AttrValue, an optional group name,
    * and the parent container.
    * @param name The local name for this state.
    * @param group An optional parent group name.
-   * @param container The parent container of this State.
+   * @param parent The parent Attribute of this AttrValue.
    */
-  constructor(name: string, parent: StateGroup) {
+  constructor(name: string, parent: Attribute) {
     super(name, parent);
     this.rulesets = new RulesetContainer(this);
   }
 
-  newChild(): never {
-    return assertNeverCalled();
-  }
+  protected get ChildConstructor(): never { return assertNeverCalled(); }
+  newChild(): never { return assertNeverCalled(); }
 
-  get isUniversal(): boolean { return this.name === UNIVERSAL_STATE; }
+  get isUniversal(): boolean { return this.uid === UNIVERSAL_ATTR_VALUE; }
 
   /**
    * Retrieve the BlockClass that this state belongs to.
@@ -51,49 +50,49 @@ export class State extends Style<State, Block, StateGroup, never> {
   get blockClass(): BlockClass { return this.parent.parent; }
 
   /**
-   * Retrieve this State's local name, including the optional BlockClass and group designations.
-   * @returns The State's local name.
+   * Retrieve this AttrValue's local name, including the optional BlockClass and group designations.
+   * @returns The AttrValue's local name.
    */
   localName(): string {
-    return `${this.parent.localName()}${this.isUniversal ? "" : `-${this.name}`}`;
+    return `${this.parent.localName()}${this.isUniversal ? "" : `-${this.uid}`}`;
   }
 
   asSourceAttributes(): Attr[] {
     if (!this._sourceAttributes) {
       let blockClass = this.blockClass;
       let rootIsOptional = true;
       this._sourceAttributes = blockClass.asSourceAttributes(rootIsOptional);
-      let value = this.isUniversal ? attrValues.absent() : attrValues.constant(this.name);
-      this._sourceAttributes.push(new AttributeNS("state", this.parent.name, value));
+      let value = this.isUniversal ? attrValues.absent() : attrValues.constant(this.uid);
+      this._sourceAttributes.push(new AttributeNS(this.parent.namespace, this.parent.name, value));
     }
     return this._sourceAttributes.slice();
   }
 
   asSource(): string {
-    return this.parent.asSource(this.name);
+    return this.parent.asSource(this.uid);
   }
 
   public cssClass(opts: OptionsReader): string {
     switch (opts.outputMode) {
       case OutputMode.BEM:
-        return `${this.parent.cssClass(opts)}${ this.isUniversal ? "" : `-${this.name}`}`;
+        return `${this.parent.cssClass(opts)}${ this.isUniversal ? "" : `-${this.uid}`}`;
       default:
         return assertNever(opts.outputMode);
     }
   }
 
-  // TODO: Implement lookup relative to State.
+  // TODO: Implement lookup relative to AttrValue.
   public lookup(): undefined { return undefined; }
 
   /**
    * Return array self and all children.
    * @returns Array of Styles.
    */
-  all(): State[] {
+  all(): AttrValue[] {
     return [this];
   }
 }
 
-export function isState(o: object): o is State {
-  return o instanceof State;
+export function isAttrValue(o: object): o is AttrValue {
+  return o instanceof AttrValue;
 }

packages/css-blocks/src/Block/Attribute.ts

@@ -0,0 +1,222 @@
+import {
+  Attr,
+  AttributeNS,
+  AttributeValueChoice,
+  ValueAbsent,
+  ValueConstant,
+} from "@opticss/element-analysis";
+import { ObjectDictionary } from "@opticss/util";
+
+import { STATE_NAMESPACE, UNIVERSAL_ATTR_VALUE } from "../BlockSyntax";
+import { OptionsReader } from "../OptionsReader";
+import { OutputMode } from "../OutputMode";
+
+import { AttrValue } from "./AttrValue";
+import { Block } from "./Block";
+import { BlockClass } from "./BlockClass";
+import { Inheritable } from "./Inheritable";
+
+export interface AttrToken {
+  namespace: string;
+  name: string;
+}
+
+function isAttrToken(o: AttrToken | string): o is AttrToken {
+  return typeof o !== "string";
+}
+
+export function attrTokenToString(token: AttrToken): string {
+  if (!isAttrToken(token)) { return String(token); }
+  return `${token.namespace}|${token.name}`;
+}
+
+export class Attribute extends Inheritable<Attribute, Block, BlockClass, AttrValue, AttrToken>
+{
+
+  private _hasValues = false;
+  private _universalValue: AttrValue | undefined;
+  private _sourceAttributes: Attr[] | undefined;
+
+  protected get ChildConstructor(): typeof AttrValue { return AttrValue; }
+  protected tokenToUid(token: AttrToken): string { return attrTokenToString(token); }
+
+  public get name(): string { return this.token.name; }
+  public get namespace(): string { return this.token.namespace; }
+
+  /**
+   * @returns If this Attribute contains anything but the "Universal" AttrValue.
+   **/
+  get hasValues(): boolean { return this._hasValues; }
+
+  /**
+   * @returns If this Attribute only contains the "Universal" AttrValue.
+   **/
+  get isBooleanAttribute(): boolean { return !this._hasValues; }
+
+  /**
+   * @returns The "Universal" Value, or `undefined`.
+   **/
+  get universalValue(): AttrValue | undefined { return this._universalValue; }
+
+  /**
+   * @returns This Attribute's parent `BlockClass`
+   **/
+  get blockClass(): BlockClass { return this.parent; }
+
+  /**
+   * @returns An array of all `AttrValue`s contained in this `Attribute`.
+   **/
+  values(): AttrValue[] { return this.children(); }
+
+  /**
+   * @returns A hash of all `Value`s contained in this `Attribute`.
+   **/
+  valuesHash(): ObjectDictionary<AttrValue> { return this.childrenHash(); }
+  resolveValuesHash(): ObjectDictionary<AttrValue> { return this.resolveChildrenHash(); }
+
+  /**
+   * @returns An Map of all `Value`s contained in this `Attribute`.
+   **/
+  valuesMap(): Map<string, AttrValue> { return this.childrenMap(); }
+  resolveValuesMap(): Map<string, AttrValue> { return this.resolveChildrenMap(); }
+
+  /**
+   * Ensures that a AttrValue of name `name` exists in this Attribute. If no
+   * `AttrValue` exists, one is created. If no name is passed, it ensures the
+   * "Universal" AttrValue.
+   * @param name  string  The `AttrValue` name to ensure.
+   * @returns The `AttrValue`
+   **/
+  ensureValue(name: string = UNIVERSAL_ATTR_VALUE) {
+    let value = this.ensureChild(name);
+    if (name !== UNIVERSAL_ATTR_VALUE) { this._hasValues = true; }
+    else { this._universalValue = value; }
+    return value;
+  }
+
+  /**
+   * Get am Attribute's own (read: non-inherited) `AttrValue` of name
+   * `name` from this `Attribute`. If no name is passed, it tries
+   * to retrieve the "Universal" AttrValue.
+   * @param name  string  The name of the `AttrValue` to retrieve.
+   * @returns The `AttrValue` or `undefined`.
+   **/
+  getValue(name: string = UNIVERSAL_ATTR_VALUE): AttrValue | null { return this.getChild(name); }
+
+  /**
+   * Get am Attribute's own or inherited `AttrValue` of name `name` from this
+   * `Attribute` or its base. If no name is passed, it tries to retrieve
+   * the "Universal" AttrValue.
+   * @param name  string  The name of the `AttrValue` to retrieve.
+   * @returns The `AttrValue` or `undefined`.
+   **/
+  resolveValue(name: string = UNIVERSAL_ATTR_VALUE): AttrValue | null { return this.resolveChild(name); }
+
+  /**
+   * @returns whether this Attribute has any Values defined, directly or inherited.
+   */
+  hasResolvedValues(): boolean {
+    return !!(this.hasValues || this.base && this.base.hasResolvedValues());
+  }
+
+  /**
+   * Resolves all AttrValues from this Attribute's inheritance
+   * chain.
+   * @returns All AttrValues this Attribute contains.
+   */
+  resolveValues(): Map<string, AttrValue> {
+    let resolved: Map<string, AttrValue> = new Map();
+    for (let base of this.resolveInheritance()) {
+      if (base.values()) {
+        resolved = new Map([...resolved, ...base._children]);
+      }
+    }
+    Object.assign(resolved, this._children);
+    return resolved;
+  }
+
+  /**
+   * @returns The bare Attribute selector with no qualifying `BlockClass` name.
+   */
+  unqualifiedSource(value?: string): string {
+    return `[${this.token.namespace}|${this.token.name}${(value && value !== UNIVERSAL_ATTR_VALUE) ? `=${value}` : ""}]`;
+  }
+
+  /**
+   * Retrieve this Attribute's selector as it appears in the Block source code.
+   *
+   * @param value If provided, it is used as the Attribute's value whether or not
+   *   it is allowed by the known AttrValues (this is useful for constructing
+   *   error messages).
+   * @returns The Attribute's attribute selector.
+   */
+  asSource(value?: string): string {
+    return (this.blockClass.isRoot ? "" : this.blockClass.asSource()) + this.unqualifiedSource(value);
+  }
+
+  /**
+   * Emit analysis attributes for the `AttrValue`s this
+   * `Attribute` represents in their authored source format.
+   */
+  asSourceAttributes(): Attr[] {
+    if (!this._sourceAttributes) {
+      this._sourceAttributes = [];
+      this._sourceAttributes.push(...this.blockClass.asSourceAttributes());
+      let value: AttributeValueChoice | ValueAbsent;
+      if (this.hasValues) {
+        let values = new Array<ValueConstant>();
+        for (let value of this.values()) {
+          values.push({ constant: value.uid });
+        }
+        value = { oneOf: values };
+      } else {
+        value = { absent: true };
+      }
+      this._sourceAttributes.push(new AttributeNS(STATE_NAMESPACE, this.name, value));
+    }
+    return this._sourceAttributes;
+  }
+
+  /**
+   * Retrieve this AttrValue's local name, including the optional BlockClass and group designations.
+   * @returns The AttrValue's local name.
+   */
+  localName(): string {
+    if (this.blockClass.isRoot) {
+      return this.uid;
+    } else {
+      return `${this.blockClass.localName()}--${this.token.namespace}-${this.token.name}`;
+    }
+  }
+
+  /**
+   * Export as new class name.
+   * @param opts Option hash configuring output mode.
+   * @returns String representing output class.
+   */
+  cssClass(opts: OptionsReader) {
+    switch (opts.outputMode) {
+      case OutputMode.BEM:
+        let cssClassName = this.blockClass.cssClass(opts);
+        return `${cssClassName}--${this.token.name}`;
+      default:
+        throw new Error("this never happens");
+    }
+  }
+
+  /**
+   * Return array self and all children.
+   * @returns Array of Styles.
+   */
+  all(): Attribute[] {
+    return [this];
+  }
+}
+
+/**
+ * @param o object  The object to test.
+ * @returns If the supplied object `o` is a `Attribute`.
+ */
+export function isAttribute(o: object): o is Attribute {
+  return o instanceof Attribute;
+}