@tempoxyz/ds 0.3.10 → 0.3.13

package/src/oxlint/rules/PreferComponent.ts

@@ -1,11 +1,13 @@
 /** Points native HTML controls and structures at the Web components that replace them. @module */
 import type { ESTree, Rule } from '@oxlint/plugins'
+import * as Docs from '../internal/Docs.ts'
 
 // Each element maps to the component that renders it with Tempo styles, states, and semantics.
 const elements: Record<string, string> = {
   button: 'Button',
   details: 'Accordion',
   dialog: 'Dialog',
+  dl: 'ListGroup',
   fieldset: 'Fieldset',
   hr: 'Separator',
   kbd: 'Kbd',
@@ -35,8 +37,9 @@ const inputs: Record<string, string> = {
 }
 
 /**
- * Reports a native element that a `@tempoxyz/ds` component replaces, such as `<button>` or
- * `<input type="checkbox">`. Elements inside a `render` prop are skipped, since the component that
+ * Reports a native element that a `@tempoxyz/ds` component replaces, such as `<button>`,
+ * `<input type="checkbox">`, or a `<dl>` of labels and values. The message links the docs page of
+ * the component. Elements inside a `render` prop are skipped, since the component that
  * receives them supplies the styles.
  */
 export const rule: Rule = {
@@ -45,7 +48,7 @@ export const rule: Rule = {
       description: 'Prefer `@tempoxyz/ds` components over the native elements they replace.',
     },
     messages: {
-      component: "Use '{{component}}' from '@tempoxyz/ds' instead of <{{element}}>.",
+      component: "Use '{{component}}' from '@tempoxyz/ds' instead of <{{element}}>. See {{url}}",
     },
     schema: [
       {
@@ -95,7 +98,11 @@ export const rule: Rule = {
 
         if (replacement)
           context.report({
-            data: { component: replacement, element: node.name.name },
+            data: {
+              component: replacement,
+              element: node.name.name,
+              url: Docs.component(replacement),
+            },
             messageId: 'component',
             node,
           })

package/src/oxlint/rules/PreferLayout.ts

@@ -0,0 +1,96 @@
+/** Points plain flex and grid wrappers at `Stack`, `Inline`, and `Grid`. @module */
+import type { Rule } from '@oxlint/plugins'
+import * as Docs from '../internal/Docs.ts'
+import * as Styles from '../internal/Styles.ts'
+
+// Block elements that a layout component renders through `render`.
+const tags = new Set([
+  'article',
+  'aside',
+  'div',
+  'footer',
+  'form',
+  'header',
+  'main',
+  'nav',
+  'ol',
+  'section',
+  'ul',
+])
+
+// Declarations that the layout components set. Any other declaration makes the element more than a
+// layout wrapper, so the rule skips it.
+const layout = new Set([
+  'alignItems',
+  'columnGap',
+  'display',
+  'flexDirection',
+  'flexWrap',
+  'gap',
+  'gridTemplateColumns',
+  'justifyContent',
+  'rowGap',
+])
+
+// Equal tracks that `columns` or `fit` on `Grid` produce.
+const tracks = /^repeat\(\s*(?:[1-46]|12|auto-fill|auto-fit)\s*,/
+
+/**
+ * Reports a block element whose only styles lay out its children with flex or grid and a gap.
+ * A column maps to `Stack`, a row to `Inline`, and equal grid tracks to `Grid`. An element
+ * with a `className`, a spread that the rule cannot read, or any other declaration passes.
+ */
+export const rule: Rule = {
+  meta: {
+    docs: {
+      description: 'Use `Stack`, `Inline`, or `Grid` instead of a plain flex or grid wrapper.',
+    },
+    messages: {
+      layout:
+        "Use '{{component}}' from '@tempoxyz/ds' instead of laying out <{{element}}> with {{display}} and a gap. See {{url}}",
+    },
+    schema: [],
+    type: 'suggestion',
+  },
+  create(context) {
+    return Styles.visit((element) => {
+      if (!tags.has(element.tag) || element.open) return
+
+      const declarations = element.declarations
+
+      if (![...declarations.keys()].every((property) => layout.has(property))) return
+      if (!['columnGap', 'gap', 'rowGap'].some((property) => declarations.has(property))) return
+
+      const display = Styles.text(declarations.get('display'))
+      const component = (() => {
+        if (display === 'flex' || display === 'inline-flex') {
+          const direction = declarations.has('flexDirection')
+            ? Styles.text(declarations.get('flexDirection'))
+            : 'row'
+
+          if (direction === 'column') return 'Stack'
+          if (direction === 'row') return 'Inline'
+          return undefined
+        }
+        if (display !== 'grid' && display !== 'inline-grid') return undefined
+        if (!declarations.has('gridTemplateColumns')) return 'Stack'
+
+        const columns = Styles.text(declarations.get('gridTemplateColumns'))
+
+        return columns !== undefined && tracks.test(columns) ? 'Grid' : undefined
+      })()
+
+      if (component)
+        context.report({
+          data: {
+            component,
+            display: display?.replace('inline-', '') ?? '',
+            element: element.tag,
+            url: Docs.component(component),
+          },
+          messageId: 'layout',
+          node: element.node,
+        })
+    })
+  },
+}

package/src/oxlint/rules/PreferProgress.ts

@@ -0,0 +1,49 @@
+/** Points hand-built bars at `Progress` and `ListGroup.Meter`. @module */
+import type { ESTree, Rule } from '@oxlint/plugins'
+import * as Docs from '../internal/Docs.ts'
+import * as Styles from '../internal/Styles.ts'
+
+/**
+ * Reports an empty `div` or `span` whose inline `width` or `inlineSize` is a computed percentage,
+ * such as a template literal that ends in `%`, which draws the fill of a hand-built bar. An element
+ * with children passes, since a resizable pane sets its width the same way.
+ */
+export const rule: Rule = {
+  meta: {
+    docs: { description: 'Use `Progress` or `ListGroup.Meter` instead of a hand-built bar.' },
+    messages: {
+      bar: "Use 'Progress' from '@tempoxyz/ds', or 'ListGroup.Meter' in a ListGroup row, instead of drawing a bar with <{{element}}> and a percentage width. See {{url}}",
+    },
+    schema: [],
+    type: 'suggestion',
+  },
+  create(context) {
+    function percentage(node: ESTree.Node | undefined) {
+      if (node?.type === 'TemplateLiteral')
+        return node.expressions.length > 0 && node.quasis.at(-1)?.value.cooked?.trim() === '%'
+      if (node?.type === 'BinaryExpression')
+        return node.operator === '+' && node.right.type === 'Literal' && node.right.value === '%'
+      return false
+    }
+
+    return Styles.visit((element) => {
+      if (element.tag !== 'div' && element.tag !== 'span') return
+
+      const parent = element.node.parent
+      const empty =
+        parent.type === 'JSXElement' &&
+        parent.children.every((child) => child.type === 'JSXText' && child.value.trim() === '')
+
+      if (!empty) return
+      if (
+        percentage(element.declarations.get('width')) ||
+        percentage(element.declarations.get('inlineSize'))
+      )
+        context.report({
+          data: { element: element.tag, url: Docs.component('Progress') },
+          messageId: 'bar',
+          node: element.node,
+        })
+    })
+  },
+}

package/src/oxlint/rules/PreferSurface.ts

@@ -0,0 +1,70 @@
+/** Points native elements styled as cards at `Surface`. @module */
+import type { Rule } from '@oxlint/plugins'
+import * as Docs from '../internal/Docs.ts'
+import * as Styles from '../internal/Styles.ts'
+
+// Elements that render a card's container. Inline elements and controls draw other components.
+const tags = new Set(['article', 'aside', 'div', 'li', 'section'])
+
+// Values that draw nothing, so the declaration does not make the element a card.
+const empty = /^(?:0(?:\.0+)?(?:px|rem)?|initial|none|transparent|unset)$/
+
+/**
+ * Reports an `article`, `aside`, `div`, `li`, or `section` whose styles draw a card: a corner
+ * radius and padding with a border or a background. A pill radius, such as `full`, and a
+ * positioned element, such as a hand-built popover, pass.
+ */
+export const rule: Rule = {
+  meta: {
+    docs: { description: 'Use `Surface` instead of a native element styled as a card.' },
+    messages: {
+      surface:
+        "Use 'Surface' from '@tempoxyz/ds' instead of styling <{{element}}> as a card. It sets the radius and padding together. See {{url}}",
+    },
+    schema: [],
+    type: 'suggestion',
+  },
+  create(context) {
+    return Styles.visit((element) => {
+      if (!tags.has(element.tag)) return
+
+      const declarations = element.declarations
+
+      function set(property: string) {
+        const node = declarations.get(property)
+
+        if (!node) return false
+
+        const value = Styles.text(node)
+
+        return value === undefined || !empty.test(value)
+      }
+
+      const properties = [...declarations.keys()]
+      const position = Styles.text(declarations.get('position'))
+      const radius = properties.some((property) => {
+        if (!property.endsWith('Radius') || !set(property)) return false
+
+        const value = Styles.text(declarations.get(property))
+
+        return value === undefined || !/^(?:50%|9{3,}(?:px)?|full)$/.test(value)
+      })
+      const padding = properties.some((property) => property.startsWith('padding') && set(property))
+      const border = properties.some(
+        (property) =>
+          /^border(?:Block|Bottom|Inline|Left|Right|Top)?(?:End|Start)?(?:Style|Width)?$/.test(
+            property,
+          ) && set(property),
+      )
+      const background = set('background') || set('backgroundColor')
+
+      if (position === 'absolute' || position === 'fixed' || position === 'sticky') return
+      if (radius && padding && (border || background))
+        context.report({
+          data: { element: element.tag, url: Docs.component('Surface') },
+          messageId: 'surface',
+          node: element.node,
+        })
+    })
+  },
+}

package/src/oxlint/rules/RequireAccessibleName.ts

@@ -13,8 +13,10 @@ const list = new Intl.ListFormat('en', { type: 'disjunction' })
 const web = ['aria-label', 'aria-labelledby']
 const mobile = ['accessibilityLabel', 'accessibilityLabelledBy', 'aria-label', 'aria-labelledby']
 
-// Components from each surface whose rendered output has no text to name it.
+// Components from each surface whose rendered output has no text to name it. Marketing ships no
+// components yet.
 const targets: Record<Imports.Surface, Record<string, Target>> = {
+  marketing: {},
   mobile: { IconButton: { names: mobile } },
   web: {
     Button: { names: web, when: { attribute: 'shape', value: 'icon' } },

package/src/oxlint/rules/RequireScrollRegion.ts

@@ -0,0 +1,92 @@
+/** Requires a name, a role, and a tab stop on native scroll containers. @module */
+import type { ESTree, Rule } from '@oxlint/plugins'
+import * as Docs from '../internal/Docs.ts'
+import * as Styles from '../internal/Styles.ts'
+
+const list = new Intl.ListFormat('en', { type: 'conjunction' })
+
+// Native elements and component names that take focus, so the region's content holds a tab stop.
+const focusable =
+  /^(?:a|button|input|select|summary|textarea|.*(?:Button|Input|Link|Select|Trigger))$/
+
+const overflows = ['overflow', 'overflowBlock', 'overflowInline', 'overflowX', 'overflowY']
+
+/**
+ * Reports a native element that scrolls, through `overflow` set to `auto` or `scroll`, without
+ * `role`, `tabIndex`, and `aria-label` or `aria-labelledby`. Keyboards scroll only a focusable
+ * region, and screen readers announce the region by its name. An element with a spread that the
+ * rule cannot read passes, since the spread can supply the attributes, and so does a container whose
+ * content holds a link, a button, a field, or an element with `tabIndex`.
+ */
+export const rule: Rule = {
+  meta: {
+    docs: { description: 'Name scroll containers and make them focusable.' },
+    messages: {
+      region:
+        'This scrolling <{{element}}> needs {{missing}}, so keyboard and screen reader users can reach and identify it. See {{url}}',
+    },
+    schema: [],
+    type: 'problem',
+  },
+  create(context) {
+    function attribute(node: ESTree.JSXOpeningElement, names: readonly string[]) {
+      return node.attributes.some(
+        (attribute) =>
+          attribute.type === 'JSXAttribute' &&
+          attribute.name.type === 'JSXIdentifier' &&
+          names.includes(attribute.name.name),
+      )
+    }
+
+    // Whether the JSX inside `node` renders an element that takes focus.
+    function interactive(node: ESTree.Node): boolean {
+      if (node.type === 'JSXOpeningElement') {
+        const name = context.sourceCode.getText(node.name).split('.').at(-1) ?? ''
+
+        if (focusable.test(name) || attribute(node, ['href', 'tabIndex'])) return true
+      }
+
+      return (context.sourceCode.visitorKeys[node.type] ?? []).some((field) => {
+        const value: unknown = Reflect.get(node, field)
+
+        return (Array.isArray(value) ? value : [value]).some(
+          (child) => child && typeof child === 'object' && 'type' in child && interactive(child),
+        )
+      })
+    }
+
+    return Styles.visit((element) => {
+      if (element.spread) return
+
+      const scrolls = overflows.some((property) => {
+        const value = Styles.text(element.declarations.get(property))
+
+        return value !== undefined && /\b(?:auto|scroll)\b/.test(value)
+      })
+
+      if (!scrolls) return
+      if (
+        element.node.parent.type === 'JSXElement' &&
+        element.node.parent.children.some(interactive)
+      )
+        return
+
+      const missing = [
+        ...(attribute(element.node, ['role']) ? [] : ['role="region"']),
+        ...(attribute(element.node, ['tabIndex']) ? [] : ['tabIndex={0}']),
+        ...(attribute(element.node, ['aria-label', 'aria-labelledby']) ? [] : ['an aria-label']),
+      ]
+
+      if (missing.length > 0)
+        context.report({
+          data: {
+            element: element.tag,
+            missing: list.format(missing),
+            url: Docs.page('patterns/responsive-layout#scroll-wide-content-inside-its-own-region'),
+          },
+          messageId: 'region',
+          node: element.node,
+        })
+    })
+  },
+}