@hussmartinez/sdk-config 0.0.0-stage → 0.1.0

package/src/stylelint/plugins/layer-name-pattern.js

@@ -0,0 +1,96 @@
+import stylelint from "stylelint";
+import { adrUrl } from "./adr.js";
+
+const {
+  createPlugin,
+  utils: { report, ruleMessages, validateOptions },
+} = stylelint;
+
+const ruleName = "hm/layer-name-pattern";
+
+const messages = ruleMessages(ruleName, {
+  /** @param {string} name */
+  expected: (name) => `Expected layer "${name}" to be "hm" or a sublayer such as "hm.sdk"`,
+  anonymous: () => `Unexpected anonymous layer. Name it "hm" or a sublayer such as "hm.sdk"`,
+});
+
+const LAYER_NAME = /^hm(?:\.[a-z][a-z0-9-]*)*$/;
+const IMPORT_LAYER = /\blayer\b(?:\(\s*([^)]*?)\s*\))?/i;
+const IMPORT_URL = /url\([^)]*\)|"[^"]*"|'[^']*'/gi;
+
+/**
+ * Cascade layers are global to the page, so every layer an SDK declares must
+ * sit inside the `hm` layer (ADR 0003, ADR 0005). A layer nested in a layer
+ * block takes the outer name as its prefix, so only the outermost is checked.
+ *
+ * @type {import("stylelint").Rule<boolean>}
+ */
+const rule = (primary) => (root, result) => {
+  if (!validateOptions(result, ruleName, { actual: primary, possible: [true] })) {
+    return;
+  }
+
+  root.walkAtRules((atRule) => {
+    const name = atRule.name.toLowerCase();
+    if (name !== "layer" && name !== "import") {
+      return;
+    }
+    if (name === "layer" && isInsideLayerBlock(atRule)) {
+      return;
+    }
+
+    for (const layer of declaredLayers(atRule, name)) {
+      if (layer === null) {
+        report({ result, ruleName, node: atRule, message: messages.anonymous() });
+      } else if (!LAYER_NAME.test(layer)) {
+        report({ result, ruleName, node: atRule, message: messages.expected(layer), word: layer });
+      }
+    }
+  });
+};
+
+/**
+ * Lists the layers an at-rule declares. `null` stands for an anonymous layer.
+ *
+ * @param {import("postcss").AtRule} atRule
+ * @param {string} name
+ * @returns {Array<string | null>}
+ */
+function declaredLayers(atRule, name) {
+  if (name === "import") {
+    const match = IMPORT_LAYER.exec(atRule.params.replace(IMPORT_URL, ""));
+    if (!match) {
+      return [];
+    }
+    return [match[1] || null];
+  }
+  const names = atRule.params
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  return names.length > 0 ? names : [null];
+}
+
+/**
+ * @param {import("postcss").AtRule} atRule
+ * @returns {boolean}
+ */
+function isInsideLayerBlock(atRule) {
+  /** @type {import("postcss").Container | import("postcss").Document | undefined} */
+  let parent = atRule.parent;
+  for (; parent; parent = parent.parent) {
+    if (
+      parent.type === "atrule" &&
+      /** @type {import("postcss").AtRule} */ (parent).name === "layer"
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+rule.ruleName = ruleName;
+rule.messages = messages;
+rule.meta = { url: adrUrl("0003-hm-namespace.md") };
+
+export default createPlugin(ruleName, rule);

package/src/stylelint/plugins/named-colors.js

@@ -0,0 +1,157 @@
+/**
+ * The 148 named colours of CSS Color Module Level 4.
+ *
+ * `transparent`, `currentcolor` and the system colours are deliberately
+ * absent: they don't encode a design decision, and system colours are needed
+ * for forced-colours mode.
+ */
+export const NAMED_COLORS = new Set([
+  "aliceblue",
+  "antiquewhite",
+  "aqua",
+  "aquamarine",
+  "azure",
+  "beige",
+  "bisque",
+  "black",
+  "blanchedalmond",
+  "blue",
+  "blueviolet",
+  "brown",
+  "burlywood",
+  "cadetblue",
+  "chartreuse",
+  "chocolate",
+  "coral",
+  "cornflowerblue",
+  "cornsilk",
+  "crimson",
+  "cyan",
+  "darkblue",
+  "darkcyan",
+  "darkgoldenrod",
+  "darkgray",
+  "darkgreen",
+  "darkgrey",
+  "darkkhaki",
+  "darkmagenta",
+  "darkolivegreen",
+  "darkorange",
+  "darkorchid",
+  "darkred",
+  "darksalmon",
+  "darkseagreen",
+  "darkslateblue",
+  "darkslategray",
+  "darkslategrey",
+  "darkturquoise",
+  "darkviolet",
+  "deeppink",
+  "deepskyblue",
+  "dimgray",
+  "dimgrey",
+  "dodgerblue",
+  "firebrick",
+  "floralwhite",
+  "forestgreen",
+  "fuchsia",
+  "gainsboro",
+  "ghostwhite",
+  "gold",
+  "goldenrod",
+  "gray",
+  "green",
+  "greenyellow",
+  "grey",
+  "honeydew",
+  "hotpink",
+  "indianred",
+  "indigo",
+  "ivory",
+  "khaki",
+  "lavender",
+  "lavenderblush",
+  "lawngreen",
+  "lemonchiffon",
+  "lightblue",
+  "lightcoral",
+  "lightcyan",
+  "lightgoldenrodyellow",
+  "lightgray",
+  "lightgreen",
+  "lightgrey",
+  "lightpink",
+  "lightsalmon",
+  "lightseagreen",
+  "lightskyblue",
+  "lightslategray",
+  "lightslategrey",
+  "lightsteelblue",
+  "lightyellow",
+  "lime",
+  "limegreen",
+  "linen",
+  "magenta",
+  "maroon",
+  "mediumaquamarine",
+  "mediumblue",
+  "mediumorchid",
+  "mediumpurple",
+  "mediumseagreen",
+  "mediumslateblue",
+  "mediumspringgreen",
+  "mediumturquoise",
+  "mediumvioletred",
+  "midnightblue",
+  "mintcream",
+  "mistyrose",
+  "moccasin",
+  "navajowhite",
+  "navy",
+  "oldlace",
+  "olive",
+  "olivedrab",
+  "orange",
+  "orangered",
+  "orchid",
+  "palegoldenrod",
+  "palegreen",
+  "paleturquoise",
+  "palevioletred",
+  "papayawhip",
+  "peachpuff",
+  "peru",
+  "pink",
+  "plum",
+  "powderblue",
+  "purple",
+  "rebeccapurple",
+  "red",
+  "rosybrown",
+  "royalblue",
+  "saddlebrown",
+  "salmon",
+  "sandybrown",
+  "seagreen",
+  "seashell",
+  "sienna",
+  "silver",
+  "skyblue",
+  "slateblue",
+  "slategray",
+  "slategrey",
+  "snow",
+  "springgreen",
+  "steelblue",
+  "tan",
+  "teal",
+  "thistle",
+  "tomato",
+  "turquoise",
+  "violet",
+  "wheat",
+  "white",
+  "whitesmoke",
+  "yellow",
+  "yellowgreen",
+]);

package/src/stylelint/plugins/no-literal-values.js

@@ -0,0 +1,249 @@
+import valueParser from "postcss-value-parser";
+import stylelint from "stylelint";
+import { adrUrl } from "./adr.js";
+import { NAMED_COLORS } from "./named-colors.js";
+
+const {
+  createPlugin,
+  utils: { report, ruleMessages, validateOptions },
+} = stylelint;
+
+const ruleName = "hm/no-literal-values";
+
+const messages = ruleMessages(ruleName, {
+  /**
+   * @param {string} kind
+   * @param {string} value
+   */
+  rejected: (kind, value) => `Unexpected literal ${kind} "${value}". Use a --hm-* design token`,
+});
+
+const LENGTH_UNITS = new Set([
+  "cap",
+  "ch",
+  "cm",
+  "cqb",
+  "cqh",
+  "cqi",
+  "cqmax",
+  "cqmin",
+  "cqw",
+  "dvb",
+  "dvh",
+  "dvi",
+  "dvmax",
+  "dvmin",
+  "dvw",
+  "em",
+  "ex",
+  "ic",
+  "in",
+  "lh",
+  "lvb",
+  "lvh",
+  "lvi",
+  "lvmax",
+  "lvmin",
+  "lvw",
+  "mm",
+  "pc",
+  "pt",
+  "px",
+  "q",
+  "rcap",
+  "rch",
+  "rem",
+  "rex",
+  "ric",
+  "rlh",
+  "svb",
+  "svh",
+  "svi",
+  "svmax",
+  "svmin",
+  "svw",
+  "vb",
+  "vh",
+  "vi",
+  "vmax",
+  "vmin",
+  "vw",
+]);
+const TIME_UNITS = new Set(["ms", "s"]);
+const COLOR_FUNCTIONS = new Set([
+  "color",
+  "device-cmyk",
+  "hsl",
+  "hsla",
+  "hwb",
+  "lab",
+  "lch",
+  "oklab",
+  "oklch",
+  "rgb",
+  "rgba",
+]);
+const EASING_FUNCTIONS = new Set(["cubic-bezier", "linear", "steps"]);
+const EASING_KEYWORDS = new Set([
+  "ease",
+  "ease-in",
+  "ease-in-out",
+  "ease-out",
+  "linear",
+  "step-end",
+  "step-start",
+]);
+const GLOBAL_KEYWORDS = new Set(["inherit", "initial", "revert", "revert-layer", "unset"]);
+const MATH_OPERATORS = new Set(["*", "+", "-", "/"]);
+const OPAQUE_FUNCTIONS = new Set(["attr", "env", "format", "image-set", "local", "url"]);
+
+/** Properties whose unitless numbers are design values. */
+const NUMERIC_TOKEN_PROPERTIES = new Set(["font-weight", "line-height", "opacity", "z-index"]);
+/** Properties where every keyword other than a CSS-wide one is a literal font value. */
+const FONT_PROPERTIES = new Set(["font", "font-family", "font-size", "font-weight", "line-height"]);
+const EASING_PROPERTIES = new Set([
+  "animation",
+  "animation-timing-function",
+  "transition",
+  "transition-timing-function",
+]);
+const COLOR_PROPERTY =
+  /color|background|border|outline|shadow|fill|stroke|caret|column-rule|decoration|emphasis|scrollbar/;
+
+/**
+ * Every colour, length, duration, easing, shadow, z-index, opacity and font
+ * value must come from a `--hm-*` token, so themes can change any of them
+ * (ADR 0006). Literals are only allowed where they carry no design decision:
+ * zero, percentages, `fr`, angles, unitless multipliers such as `flex: 1`,
+ * `transparent`, `currentColor`, system colours and CSS-wide keywords.
+ * At-rule preludes, such as container query breakpoints, aren't checked.
+ *
+ * Token definition files are exempted by the preset's `overrides`.
+ *
+ * @type {import("stylelint").Rule<boolean>}
+ */
+const rule = (primary) => (root, result) => {
+  if (!validateOptions(result, ruleName, { actual: primary, possible: [true] })) {
+    return;
+  }
+
+  root.walkDecls((decl) => {
+    const property = decl.prop.toLowerCase();
+    const isCustomProperty = property.startsWith("--");
+    const context = {
+      property,
+      colorBearing: isCustomProperty || COLOR_PROPERTY.test(property),
+      easingBearing: EASING_PROPERTIES.has(property),
+      fontProperty: FONT_PROPERTIES.has(property),
+    };
+
+    valueParser(decl.value).walk((node) => {
+      const kind = literalKind(node, context);
+      if (kind === "skip") {
+        return false;
+      }
+      if (kind) {
+        report({
+          result,
+          ruleName,
+          node: decl,
+          message: messages.rejected(kind, valueParser.stringify(node)),
+          word: valueParser.stringify(node),
+        });
+        return false;
+      }
+      return undefined;
+    });
+  });
+};
+
+/**
+ * @typedef {object} DeclarationContext
+ * @property {string} property
+ * @property {boolean} colorBearing
+ * @property {boolean} easingBearing
+ * @property {boolean} fontProperty
+ */
+
+/**
+ * Classifies one value node. Returns the kind of literal it is, `"skip"` for
+ * nodes whose contents mustn't be inspected, or `null` when it's allowed.
+ *
+ * @param {valueParser.Node} node
+ * @param {DeclarationContext} context
+ * @returns {string | null}
+ */
+function literalKind(node, context) {
+  if (node.type === "function") {
+    const name = node.value.toLowerCase();
+    if (OPAQUE_FUNCTIONS.has(name)) {
+      return "skip";
+    }
+    if (COLOR_FUNCTIONS.has(name)) {
+      return "colour";
+    }
+    if (EASING_FUNCTIONS.has(name)) {
+      return "easing";
+    }
+    return null;
+  }
+
+  if (node.type === "string") {
+    return context.fontProperty ? "font value" : null;
+  }
+
+  if (node.type !== "word") {
+    return null;
+  }
+
+  const word = node.value.toLowerCase();
+  if (word.startsWith("--") || GLOBAL_KEYWORDS.has(word) || MATH_OPERATORS.has(word)) {
+    return null;
+  }
+  if (/^#[0-9a-f]{3,8}$/.test(word)) {
+    return "colour";
+  }
+
+  const dimension = valueParser.unit(word);
+  if (dimension && dimension.number !== "" && Number.isFinite(Number(dimension.number))) {
+    const number = Number(dimension.number);
+    const unit = dimension.unit.toLowerCase();
+    if (number === 0) {
+      return null;
+    }
+    if (LENGTH_UNITS.has(unit)) {
+      return "length";
+    }
+    if (TIME_UNITS.has(unit)) {
+      return "duration";
+    }
+    if (unit !== "" && unit !== "%") {
+      return null;
+    }
+    if (context.property === "font") {
+      return "font value";
+    }
+    if (NUMERIC_TOKEN_PROPERTIES.has(context.property)) {
+      const fullyOpaque = number === (unit === "%" ? 100 : 1);
+      return context.property === "opacity" && fullyOpaque ? null : context.property;
+    }
+    return null;
+  }
+
+  if (context.fontProperty) {
+    return "font value";
+  }
+  if (context.easingBearing && EASING_KEYWORDS.has(word)) {
+    return "easing";
+  }
+  if (context.colorBearing && NAMED_COLORS.has(word)) {
+    return "colour";
+  }
+  return null;
+}
+
+rule.ruleName = ruleName;
+rule.messages = messages;
+rule.meta = { url: adrUrl("0006-design-tokens-and-theming.md") };
+
+export default createPlugin(ruleName, rule);

package/src/stylelint/plugins/selector-scope.js

@@ -0,0 +1,190 @@
+import selectorParser from "postcss-selector-parser";
+import stylelint from "stylelint";
+import { adrUrl } from "./adr.js";
+
+const {
+  createPlugin,
+  utils: { report, ruleMessages, validateOptions },
+} = stylelint;
+
+const ruleName = "hm/selector-scope";
+
+const messages = ruleMessages(ruleName, {
+  /** @param {string} selector */
+  rejected: (selector) =>
+    `Expected "${selector}" to match only elements inside an hm root, such as ".hm-pdf-editor" or "[data-hm-theme]"`,
+});
+
+const HM_NAME = /^hm-/i;
+const HM_DATA_ATTRIBUTE = /^data-hm-/i;
+const SCOPING_PSEUDOS = new Set([":is", ":where", ":matches"]);
+const SIBLING_COMBINATORS = new Set(["+", "~"]);
+
+/**
+ * SDK styles must never reach the host page (ADR 0005). A selector is scoped
+ * when the element it styles is, or is inside, an hm-namespaced element:
+ * an `.hm-*` class, `#hm-*` id, `[data-hm-*]` attribute, `<hm-*>` element or
+ * `:host`. A sibling of an hm root is outside it, so `.hm-a + p` is rejected.
+ *
+ * `:root` is allowed only for rules that declare nothing but `--hm-*` custom
+ * properties, which is how themes publish tokens. Nested rules inherit their
+ * parent's scope and aren't checked again.
+ *
+ * @type {import("stylelint").Rule<boolean>}
+ */
+const rule = (primary) => (root, result) => {
+  if (!validateOptions(result, ruleName, { actual: primary, possible: [true] })) {
+    return;
+  }
+
+  root.walkRules((ruleNode) => {
+    if (hasScopedAncestor(ruleNode)) {
+      return;
+    }
+
+    /** @type {selectorParser.Root} */
+    let selectors;
+    try {
+      selectors = selectorParser().astSync(ruleNode.selector);
+    } catch {
+      // Unparseable selectors are reported by the CSS parser and by Biome.
+      return;
+    }
+
+    const tokensOnly = declaresOnlyTokens(ruleNode);
+    for (const selector of selectors.nodes) {
+      if (isScoped(selector) || (tokensOnly && isRoot(selector))) {
+        continue;
+      }
+      const text = selector.toString().trim();
+      report({ result, ruleName, node: ruleNode, message: messages.rejected(text), word: text });
+    }
+  });
+};
+
+/**
+ * Walks the compound selectors from left to right, tracking whether the
+ * current element has an hm-namespaced ancestor. Descendant and child
+ * combinators make an anchored compound an ancestor. A sibling shares its
+ * parent, so it keeps the ancestors but not the anchor itself.
+ *
+ * @param {selectorParser.Selector} selector
+ * @returns {boolean}
+ */
+function isScoped(selector) {
+  let insideAnchor = false;
+  let compoundAnchored = false;
+  for (const node of selector.nodes) {
+    if (node.type === "combinator") {
+      if (!SIBLING_COMBINATORS.has(node.value.trim())) {
+        insideAnchor ||= compoundAnchored;
+      }
+      compoundAnchored = false;
+    } else if (isAnchor(node)) {
+      compoundAnchored = true;
+    }
+  }
+  return insideAnchor || compoundAnchored;
+}
+
+/**
+ * @param {selectorParser.Node} node
+ * @returns {boolean}
+ */
+function isAnchor(node) {
+  switch (node.type) {
+    case "class":
+    case "id":
+    case "tag":
+      return HM_NAME.test(node.value);
+    case "attribute":
+      return HM_DATA_ATTRIBUTE.test(node.attribute);
+    case "pseudo": {
+      const name = node.value.toLowerCase();
+      if (name === ":host") {
+        return true;
+      }
+      return (
+        SCOPING_PSEUDOS.has(name) &&
+        node.nodes.length > 0 &&
+        node.nodes.every((inner) => isScoped(inner))
+      );
+    }
+    default:
+      return false;
+  }
+}
+
+/**
+ * @param {selectorParser.Selector} selector
+ * @returns {boolean}
+ */
+function isRoot(selector) {
+  const [only, ...rest] = selector.nodes;
+  return rest.length === 0 && only?.type === "pseudo" && only.value.toLowerCase() === ":root";
+}
+
+/**
+ * @param {import("postcss").Rule} ruleNode
+ * @returns {boolean}
+ */
+function declaresOnlyTokens(ruleNode) {
+  const nodes = ruleNode.nodes ?? [];
+  const declarations = nodes.filter((node) => node.type === "decl");
+  return (
+    declarations.length > 0 &&
+    nodes.every((node) => node.type === "comment" || node.type === "decl") &&
+    declarations.every((decl) => decl.prop.startsWith("--hm-"))
+  );
+}
+
+/**
+ * Rules nested in another rule inherit its scope, and keyframe selectors
+ * aren't element selectors. `@scope (.hm-*)` scopes everything inside it.
+ *
+ * @param {import("postcss").Rule} ruleNode
+ * @returns {boolean}
+ */
+function hasScopedAncestor(ruleNode) {
+  /** @type {import("postcss").Container | import("postcss").Document | undefined} */
+  let parent = ruleNode.parent;
+  for (; parent; parent = parent.parent) {
+    if (parent.type === "rule") {
+      return true;
+    }
+    if (parent.type === "atrule") {
+      const atRule = /** @type {import("postcss").AtRule} */ (parent);
+      const name = atRule.name.toLowerCase();
+      if (name.endsWith("keyframes")) {
+        return true;
+      }
+      if (name === "scope" && isScopedScopeRoot(atRule.params)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {string} params `@scope` prelude, such as `(.hm-pdf-editor) to (.hm-pdf-page)`.
+ * @returns {boolean}
+ */
+function isScopedScopeRoot(params) {
+  const match = /^\s*\(([^)]*)\)/.exec(params);
+  if (!match?.[1]) {
+    return false;
+  }
+  try {
+    const selectors = selectorParser().astSync(match[1]);
+    return selectors.nodes.every((selector) => isScoped(selector));
+  } catch {
+    return false;
+  }
+}
+
+rule.ruleName = ruleName;
+rule.messages = messages;
+rule.meta = { url: adrUrl("0005-plain-css-with-cascade-layers.md") };
+
+export default createPlugin(ruleName, rule);