@tempoxyz/ds 0.3.11 → 0.3.13

package/src/oxlint/internal/Styles.ts

@@ -0,0 +1,240 @@
+/** Reads the style declarations that native JSX elements apply in a file. @module */
+import type { ESTree, Visitor } from '@oxlint/plugins'
+
+/** Declarations keyed by CSS property, with each value as written. */
+export type Declarations = ReadonlyMap<string, ESTree.Node>
+
+/** A native element, such as a `div`, and the declarations it applies. */
+export type Element = {
+  /**
+   * Declarations from the `style()` and `variants()` definitions that its spreads call, then
+   * from its inline `style` prop, which wins.
+   */
+  declarations: Declarations
+  /** The opening element. */
+  node: ESTree.JSXOpeningElement
+  /** Whether a `className` or a spread that is not a known style call can add declarations. */
+  open: boolean
+  /** Whether a spread that is not a known style call can add attributes. */
+  spread: boolean
+  /** The tag name, such as `div`. */
+  tag: string
+}
+
+type Pending = {
+  calls: readonly string[]
+  inline: Declarations
+  node: ESTree.JSXOpeningElement
+  open: boolean
+  spread: boolean
+  tag: string
+}
+
+/** Returns the Zyzz helper that a callee names, `style` or `variants`, directly or as a member of a config. */
+export function helper(node: ESTree.Node): 'style' | 'variants' | undefined {
+  const name = (() => {
+    if (node.type === 'Identifier') return node.name
+    if (node.type === 'MemberExpression' && !node.computed && node.property.type === 'Identifier')
+      return node.property.name
+    return undefined
+  })()
+
+  return name === 'style' || name === 'variants' ? name : undefined
+}
+
+/** Returns the property name of a non-computed object key. */
+export function key(property: ESTree.Node): string | undefined {
+  if (property.type !== 'Property' || property.computed) return undefined
+  if (property.key.type === 'Identifier') return property.key.name
+  if (property.key.type === 'Literal') return String(property.key.value)
+  return undefined
+}
+
+/**
+ * Returns the text of a literal value without its `!custom` suffix, such as `16px` for
+ * `'16px !custom'` and `2` for `2`. Returns `undefined` for a computed value.
+ */
+export function text(node: ESTree.Node | undefined): string | undefined {
+  if (node?.type === 'UnaryExpression' && node.operator === '-') {
+    const value = text(node.argument)
+
+    return value === undefined ? undefined : `-${value}`
+  }
+  if (
+    node?.type === 'Literal' &&
+    (typeof node.value === 'number' || typeof node.value === 'string')
+  )
+    return String(node.value)
+      .replace(/\s*!custom$/, '')
+      .trim()
+  if (node?.type === 'TemplateLiteral' && node.expressions.length === 0)
+    return node.quasis
+      .map((quasi) => quasi.value.cooked ?? '')
+      .join('')
+      .replace(/\s*!custom$/, '')
+      .trim()
+  return undefined
+}
+
+/**
+ * Returns a visitor that calls `fn` once the file is read, with each native element outside a
+ * `render` prop. A spread resolves when it calls a `style()` or `variants()` definition in the
+ * same file by name, such as `{...styles.card()}` for `styles.card` in `namespace styles`.
+ */
+export function visit(fn: visit.Callback): Visitor {
+  const definitions = new Map<string, Declarations>()
+  const pending: Pending[] = []
+
+  return {
+    CallExpression(node) {
+      const kind = helper(node.callee)
+      const argument = node.arguments[0]
+
+      if (!kind || argument?.type !== 'ObjectExpression') return
+
+      const name = path(node)
+
+      if (name) definitions.set(name, kind === 'style' ? read(argument) : variants(argument))
+    },
+    JSXOpeningElement(node) {
+      if (node.name.type !== 'JSXIdentifier' || !/^[a-z]/.test(node.name.name)) return
+
+      for (let parent: ESTree.Node | null = node.parent; parent; parent = parent.parent)
+        if (
+          parent.type === 'JSXAttribute' &&
+          parent.name.type === 'JSXIdentifier' &&
+          parent.name.name === 'render'
+        )
+          return
+
+      const calls: string[] = []
+      const inline = new Map<string, ESTree.Node>()
+      let open = false
+      let spread = false
+
+      for (const attribute of node.attributes) {
+        if (attribute.type === 'JSXSpreadAttribute') {
+          const call =
+            attribute.argument.type === 'CallExpression'
+              ? name(attribute.argument.callee)
+              : undefined
+
+          if (call) calls.push(call)
+          else spread = true
+          continue
+        }
+        if (attribute.name.type !== 'JSXIdentifier') continue
+        if (attribute.name.name === 'className') open = true
+        if (attribute.name.name !== 'style' || attribute.value?.type !== 'JSXExpressionContainer')
+          continue
+
+        const expression = attribute.value.expression
+        const objects = expression.type === 'ArrayExpression' ? expression.elements : [expression]
+
+        for (const object of objects)
+          if (object?.type === 'ObjectExpression')
+            for (const [field, value] of read(object)) inline.set(field, value)
+      }
+
+      pending.push({ calls, inline, node, open, spread, tag: node.name.name })
+    },
+    'Program:exit'() {
+      for (const element of pending) {
+        const declarations = new Map<string, ESTree.Node>()
+        let open = element.open || element.spread
+        let spread = element.spread
+
+        for (const call of element.calls) {
+          const definition = definitions.get(call)
+
+          if (!definition) {
+            open = true
+            spread = true
+            continue
+          }
+          for (const [field, value] of definition) declarations.set(field, value)
+        }
+        for (const [field, value] of element.inline) declarations.set(field, value)
+        fn({ declarations, node: element.node, open, spread, tag: element.tag })
+      }
+    },
+  }
+}
+
+export declare namespace visit {
+  /** Receives each native element once the whole file is read. */
+  type Callback = (element: Element) => void
+}
+
+// An identifier or a chain of identifiers, such as `styles.card`.
+function name(node: ESTree.Node): string | undefined {
+  if (node.type === 'Identifier') return node.name
+  if (node.type !== 'MemberExpression' || node.computed || node.property.type !== 'Identifier')
+    return undefined
+
+  const object = name(node.object)
+
+  return object === undefined ? undefined : `${object}.${node.property.name}`
+}
+
+// The name a definition is applied by: its variable, its object keys, and its namespaces.
+function path(node: ESTree.Node): string | undefined {
+  const parts: string[] = []
+  let current: ESTree.Node = node
+
+  for (let parent = current.parent; parent; current = parent, parent = parent.parent) {
+    if (parent.type === 'Property') {
+      const property = key(parent)
+
+      if (property === undefined || parent.value !== current) return undefined
+      parts.unshift(property)
+      continue
+    }
+    if (parent.type === 'ObjectExpression') continue
+    if (parent.type !== 'VariableDeclarator' || parent.id.type !== 'Identifier') return undefined
+    parts.unshift(parent.id.name)
+    break
+  }
+  if (parts.length === 0) return undefined
+  for (let parent = current.parent; parent; parent = parent.parent)
+    if (parent.type === 'TSModuleDeclaration' && parent.id.type === 'Identifier')
+      parts.unshift(parent.id.name)
+  return parts.join('.')
+}
+
+// Top-level declarations. Nested objects, such as `selectors` and queries, apply conditionally.
+function read(object: ESTree.ObjectExpression): Declarations {
+  const declarations = new Map<string, ESTree.Node>()
+
+  for (const property of object.properties) {
+    const field = key(property)
+
+    if (field === undefined || property.type !== 'Property') continue
+    if (property.value.type === 'ObjectExpression') continue
+    declarations.set(field, property.value)
+  }
+  return declarations
+}
+
+// The base declarations of a recipe, then the declarations of every option of every axis.
+function variants(object: ESTree.ObjectExpression): Declarations {
+  const declarations = new Map<string, ESTree.Node>()
+
+  for (const property of object.properties) {
+    if (property.type !== 'Property' || property.value.type !== 'ObjectExpression') continue
+
+    const section = key(property)
+
+    if (section === 'base')
+      for (const [field, value] of read(property.value)) declarations.set(field, value)
+    if (section !== 'variants') continue
+    for (const axis of property.value.properties) {
+      if (axis.type !== 'Property' || axis.value.type !== 'ObjectExpression') continue
+      for (const option of axis.value.properties)
+        if (option.type === 'Property' && option.value.type === 'ObjectExpression')
+          for (const [field, value] of read(option.value))
+            if (!declarations.has(field)) declarations.set(field, value)
+    }
+  }
+  return declarations
+}

package/src/oxlint/internal/Tokens.ts

@@ -0,0 +1,43 @@
+/**
+ * The Web token scales that lint messages suggest, as `src/web/vars.ts` defines them. The published
+ * `vars` module compiles to an empty object, so the plugin keeps its own copy of these scales.
+ * @module
+ */
+
+/** Container widths, keyed by their size in px. */
+export const container: readonly number[] = [
+  256, 288, 320, 384, 448, 512, 576, 672, 768, 896, 1024, 1152, 1280,
+]
+
+/** Returns the token key of a spacing or container size in px, such as `0-5` for 0.5. */
+export function key(px: number): string {
+  return String(px).replace('.', '-')
+}
+
+/** Corner radii in px, by Platform name. `full` takes the spacing step `999`. */
+export const radius: Readonly<Record<string, number>> = {
+  '2xl': 64,
+  '2xs': 8,
+  '3xs': 4,
+  full: 999,
+  lg: 32,
+  md: 24,
+  none: 0,
+  sm: 16,
+  xl: 40,
+  xs: 12,
+}
+
+/** Spacing steps in px. A key writes a fraction with a hyphen, such as `0-5` for 0.5px. */
+export const spacing: readonly number[] = [
+  -24, -20, -16, -12, -10, -8, -6, -4, 0, 0.5, 1, 1.5, 2, 3, 4, 6, 8, 10, 12, 16, 20, 24, 28, 32,
+  36, 40, 44, 48, 52, 56, 60, 64, 72, 80, 100, 120, 140, 160, 180, 200, 240, 280, 320, 360, 999,
+]
+
+/** Stacking layers, from the app shell overlay up to toasts. */
+export const zIndex: Readonly<Record<string, number>> = {
+  modal: 60,
+  overlay: 40,
+  popover: 50,
+  toast: 1000,
+}

package/src/oxlint/rules/NoCrossSurface.ts

@@ -3,8 +3,8 @@ import type { ESTree, Rule } from '@oxlint/plugins'
 import * as Imports from '../internal/Imports.ts'
 
 /**
- * Reports an import from the other surface. With `surface` set, every import from the other surface
- * is reported. Without it, the rule reports a file that imports from both surfaces.
+ * Reports an import from another surface. With `surface` set, every import from another surface
+ * is reported. Without it, the rule reports a file that imports from more than one surface.
  */
 export const rule: Rule = {
   meta: {
@@ -18,7 +18,7 @@ export const rule: Rule = {
     schema: [
       {
         additionalProperties: false,
-        properties: { surface: { enum: ['mobile', 'web'], type: 'string' } },
+        properties: { surface: { enum: ['marketing', 'mobile', 'web'], type: 'string' } },
         type: 'object',
       },
     ],

package/src/oxlint/rules/NoCustomValues.ts

@@ -0,0 +1,170 @@
+/** Finds `!custom` lengths and layers in Zyzz styles that equal a Web token. @module */
+import type { ESTree, Rule } from '@oxlint/plugins'
+import * as Docs from '../internal/Docs.ts'
+import * as Styles from '../internal/Styles.ts'
+import * as Tokens from '../internal/Tokens.ts'
+
+// Sizes that also accept a container width.
+const containers =
+  /^(?:flexBasis|inlineSize|max(?:InlineSize|Width)|min(?:InlineSize|Width)|width)$/
+
+// The longhands that set each part of a shorthand with two, three, or four parts.
+const sides: Record<number, readonly string[]> = {
+  2: ['Block', 'Inline'],
+  3: ['Top', 'Inline', 'Bottom'],
+  4: ['Top', 'Right', 'Bottom', 'Left'],
+}
+
+// Sizes and offsets, which accept spacing steps.
+const sizes =
+  /^(?:blockSize|bottom|flexBasis|height|inlineSize|inset\w*|left|max(?:BlockSize|Height|InlineSize|Width)|min(?:BlockSize|Height|InlineSize|Width)|right|textIndent|top|width)$/
+
+// Properties on the spacing scale.
+const spacing = /^(?:columnGap|gap|margin\w*|padding\w*|rowGap|scrollMargin\w*|scrollPadding\w*)$/
+
+const urls = {
+  container: Docs.page('foundations/layout#widths'),
+  radius: Docs.page('foundations/radius-and-padding'),
+  spacing: Docs.page('foundations/layout#spacing'),
+  zIndex: Docs.page('foundations/linter#use-tokens-for-custom-values'),
+}
+
+// A length in px, or `undefined` for any other value.
+function px(value: string) {
+  const match = /^(-?(?:\d*\.)?\d+)(px|rem)$/.exec(value)
+
+  if (!match?.[1]) return undefined
+  return Number(match[1]) * (match[2] === 'rem' ? 16 : 1)
+}
+
+/**
+ * Reports a `!custom` value in a `style()` or `variants()` definition that equals a Web token:
+ * a px or rem length on a spacing, radius, size, or container property that equals a step of its
+ * scale, and a number on `zIndex` that equals a layer. The message names the token to use.
+ * A `!custom` value that no token equals, such as `'13px !custom'`, is the sanctioned escape
+ * hatch and does not report.
+ */
+export const rule: Rule = {
+  meta: {
+    docs: { description: 'Use the Web token that a `!custom` length or layer equals.' },
+    messages: {
+      token:
+        "'{{property}}' sets the custom value {{value}}, which equals a token. Use {{tokens}}. See {{url}}",
+    },
+    schema: [],
+    type: 'suggestion',
+  },
+  create(context) {
+    // The advice for a property and its value, or `undefined` when no token replaces it.
+    function advise(property: string, value: string) {
+      if (property === 'zIndex') {
+        if (!/^-?\d+$/.test(value)) return undefined
+
+        const layer = Object.entries(Tokens.zIndex).find((entry) => entry[1] === Number(value))
+
+        if (!layer) return undefined
+        return { tokens: `the zIndex token '${layer[0]}'`, url: urls.zIndex }
+      }
+      if (property.endsWith('Radius')) {
+        const length = px(value)
+
+        if (length === undefined) return undefined
+
+        const step = Object.entries(Tokens.radius).find((entry) => entry[1] === length)
+
+        if (!step) return undefined
+        return { tokens: `the radius token '${step[0]}'`, url: urls.radius }
+      }
+      if (spacing.test(property)) {
+        const parts = value.split(/\s+/)
+        const lengths = parts.map((part) => (part === 'auto' ? 'auto' : px(part)))
+
+        if (lengths.some((length) => length === undefined)) return undefined
+        if (!lengths.some((length) => typeof length === 'number' && length !== 0)) return undefined
+        if (
+          lengths.some((length) => typeof length === 'number' && !Tokens.spacing.includes(length))
+        )
+          return undefined
+
+        const keys = lengths.map((length) =>
+          typeof length === 'number' ? Tokens.key(length) : 'auto',
+        )
+        const longhands = (() => {
+          if (property === 'gap') return ['rowGap', 'columnGap']
+
+          const suffixes = sides[parts.length]
+
+          return suffixes?.map((suffix) => `${property}${suffix}`)
+        })()
+
+        if (parts.length === 1)
+          return { tokens: `the spacing token '${keys[0]}'`, url: urls.spacing }
+        if (!longhands || longhands.length !== parts.length) return undefined
+        return {
+          tokens: `spacing tokens on each side: ${longhands.map((longhand, index) => `${longhand} '${keys[index]}'`).join(', ')}`,
+          url: urls.spacing,
+        }
+      }
+      if (sizes.test(property)) {
+        const length = px(value)
+
+        if (length === undefined || length === 0) return undefined
+        if (Tokens.spacing.includes(length))
+          return {
+            tokens: `the spacing token '${Tokens.key(length)}'`,
+            url: urls.spacing,
+          }
+        if (containers.test(property) && Tokens.container.includes(length))
+          return {
+            tokens: `the container token '${Tokens.key(length)}'`,
+            url: urls.container,
+          }
+      }
+      return undefined
+    }
+
+    function check(object: ESTree.ObjectExpression) {
+      for (const property of object.properties) {
+        if (property.type !== 'Property') continue
+        if (property.value.type === 'ObjectExpression') {
+          check(property.value)
+          continue
+        }
+
+        const name = Styles.key(property)
+        const node = property.value
+        const custom =
+          (node.type === 'Literal' &&
+            typeof node.value === 'string' &&
+            node.value.endsWith('!custom')) ||
+          (node.type === 'TemplateLiteral' &&
+            node.expressions.length === 0 &&
+            node.quasis
+              .map((quasi) => quasi.value.cooked ?? '')
+              .join('')
+              .endsWith('!custom')) ||
+          (name === 'zIndex' && node.type === 'Literal' && typeof node.value === 'number')
+        const value = Styles.text(node)
+
+        if (name === undefined || !custom || value === undefined) continue
+
+        const advice = advise(name, value)
+
+        if (advice)
+          context.report({
+            data: { property: name, value: context.sourceCode.getText(node), ...advice },
+            messageId: 'token',
+            node,
+          })
+      }
+    }
+
+    return {
+      CallExpression(node) {
+        if (!Styles.helper(node.callee)) return
+        for (const argument of node.arguments.slice(0, 1))
+          if (argument.type === 'ObjectExpression') check(argument)
+      },
+    }
+  },
+}

package/src/oxlint/rules/NoSingleKeyShortcuts.ts

@@ -0,0 +1,190 @@
+/** Finds single-key shortcuts that listen on the whole page. @module */
+import type { ESTree, Rule, Scope } from '@oxlint/plugins'
+import * as Docs from '../internal/Docs.ts'
+
+const events = new Set(['keydown', 'keypress', 'keyup'])
+// Hooks that return the function they receive.
+const hooks = new Set(['useCallback', 'useEffectEvent', 'useEvent'])
+const modifiers = new Set(['altKey', 'ctrlKey', 'getModifierState', 'metaKey'])
+const targets = new Set(['document', 'globalThis', 'self', 'window'])
+
+/**
+ * Reports a `keydown`, `keyup`, or `keypress` listener on `window` or `document` that compares
+ * `key` with one printable character, or `code` with a letter or digit key, without reading a
+ * modifier. A character key on the whole page fires while people type or dictate, which WCAG 2.1.4
+ * Character Key Shortcuts forbids unless people can turn it off or remap it. A handler that reads
+ * `metaKey`, `ctrlKey`, `altKey`, or `getModifierState` passes.
+ */
+export const rule: Rule = {
+  meta: {
+    docs: { description: 'Require a modifier on page-wide keyboard shortcuts.' },
+    messages: {
+      shortcut:
+        "'{{key}}' is a single-key shortcut on the whole page. Require a modifier, such as metaKey or ctrlKey, or let people turn it off or remap it (WCAG 2.1.4). Show it with 'Kbd' from '@tempoxyz/ds'. See {{url}}",
+    },
+    schema: [],
+    type: 'problem',
+  },
+  create(context) {
+    const url = Docs.page('foundations/accessibility#shortcuts')
+
+    // The character that `node` compares with a key, such as `k` for `'k'` or `'KeyK'`.
+    function character(node: ESTree.Node, property: string) {
+      if (node.type !== 'Literal' || typeof node.value !== 'string') return undefined
+      if (property === 'code')
+        return /^(?:Digit\d|Key[A-Z])$/.test(node.value) ? node.value : undefined
+      return [...node.value].length === 1 && /\S/.test(node.value) ? node.value : undefined
+    }
+
+    // `event.key` or `event.code`, also through `toLowerCase()` or `toUpperCase()`.
+    function read(node: ESTree.Node): string | undefined {
+      if (
+        node.type === 'CallExpression' &&
+        node.callee.type === 'MemberExpression' &&
+        node.callee.property.type === 'Identifier' &&
+        /^to(?:Lower|Upper)Case$/.test(node.callee.property.name)
+      )
+        return read(node.callee.object)
+      if (node.type !== 'MemberExpression' || node.computed || node.property.type !== 'Identifier')
+        return undefined
+      return node.property.name === 'key' || node.property.name === 'code'
+        ? node.property.name
+        : undefined
+    }
+
+    function resolve(node: ESTree.Node): ESTree.Node | undefined {
+      if (node.type === 'ArrowFunctionExpression' || node.type === 'FunctionExpression') return node
+      if (
+        node.type === 'CallExpression' &&
+        node.callee.type === 'Identifier' &&
+        hooks.has(node.callee.name) &&
+        node.arguments[0]
+      )
+        return resolve(node.arguments[0])
+      if (node.type !== 'Identifier') return undefined
+
+      for (
+        let scope: Scope | null = context.sourceCode.getScope(node);
+        scope;
+        scope = scope.upper
+      ) {
+        const variable = scope.set.get(node.name)
+
+        if (!variable) continue
+
+        const definition = variable.defs[0]?.node
+
+        if (definition?.type === 'FunctionDeclaration') return definition
+        if (definition?.type === 'VariableDeclarator' && definition.init)
+          return resolve(definition.init)
+        return undefined
+      }
+      return undefined
+    }
+
+    function walk(node: ESTree.Node, fn: (node: ESTree.Node) => void) {
+      fn(node)
+      for (const field of context.sourceCode.visitorKeys[node.type] ?? []) {
+        const value: unknown = Reflect.get(node, field)
+
+        for (const child of Array.isArray(value) ? value : [value])
+          if (child && typeof child === 'object' && 'type' in child) walk(child, fn)
+      }
+    }
+
+    function check(handler: ESTree.Node) {
+      const found: { character: string; node: ESTree.Node }[] = []
+      let modified = false
+
+      walk(handler, (node) => {
+        if (
+          node.type === 'MemberExpression' &&
+          node.property.type === 'Identifier' &&
+          modifiers.has(node.property.name)
+        )
+          modified = true
+        if (node.type === 'BinaryExpression' && ['!=', '!==', '==', '==='].includes(node.operator))
+          for (const [left, right] of [
+            [node.left, node.right],
+            [node.right, node.left],
+          ] as const) {
+            const property = read(left)
+            const value = property && character(right, property)
+
+            if (value) found.push({ character: value, node: right })
+          }
+        if (node.type === 'SwitchStatement') {
+          const property = read(node.discriminant)
+
+          if (property)
+            for (const entry of node.cases) {
+              const value = entry.test && character(entry.test, property)
+
+              if (value && entry.test) found.push({ character: value, node: entry.test })
+            }
+        }
+        if (
+          node.type === 'CallExpression' &&
+          node.callee.type === 'MemberExpression' &&
+          node.callee.property.type === 'Identifier' &&
+          node.callee.property.name === 'includes' &&
+          node.callee.object.type === 'ArrayExpression' &&
+          node.arguments[0]
+        ) {
+          const property = read(node.arguments[0])
+
+          if (property)
+            for (const item of node.callee.object.elements) {
+              const value = item && character(item, property)
+
+              if (value && item) found.push({ character: value, node: item })
+            }
+        }
+      })
+
+      if (modified) return
+      for (const entry of found)
+        context.report({
+          data: { key: entry.character, url },
+          messageId: 'shortcut',
+          node: entry.node,
+        })
+    }
+
+    return {
+      CallExpression(node) {
+        const callee = node.callee
+
+        if (
+          callee.type !== 'MemberExpression' ||
+          callee.property.type !== 'Identifier' ||
+          callee.property.name !== 'addEventListener'
+        )
+          return
+
+        const target = (() => {
+          if (callee.object.type === 'Identifier') return callee.object.name
+          if (
+            callee.object.type === 'MemberExpression' &&
+            callee.object.property.type === 'Identifier'
+          )
+            return callee.object.property.name
+          return undefined
+        })()
+        const [event, listener] = node.arguments
+
+        if (!target || !(targets.has(target) || target === 'body')) return
+        if (
+          event?.type !== 'Literal' ||
+          typeof event.value !== 'string' ||
+          !events.has(event.value)
+        )
+          return
+
+        const handler = listener && resolve(listener)
+
+        if (handler) check(handler)
+      },
+    }
+  },
+}