@tempoxyz/ds 0.2.0 → 0.2.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tempoxyz/ds",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "license": "MIT",
   "files": [
     "DESIGN.md",
@@ -16,6 +16,7 @@
   "description": "Tempo Design System",
   "dependencies": {
     "@base-ui/react": "^1.8.0",
+    "@oxlint/plugins": "1.79.0",
     "cuer": "0.0.3",
     "midcut": "0.2.0",
     "torph": "0.1.3"
@@ -1262,6 +1263,11 @@
       "types": "./dist/mobile/icons/index.d.ts",
       "react-native": "./src/mobile/icons/index.ts",
       "default": "./dist/mobile/icons/index.js"
+    },
+    "./oxlint": {
+      "src": "./src/oxlint/index.ts",
+      "types": "./dist/oxlint/index.d.ts",
+      "default": "./dist/oxlint/index.js"
     }
   },
   "peerDependencies": {

package/src/mobile/components/Avatar.tsx

@@ -1,5 +1,5 @@
-import { useState, type ComponentPropsWithRef } from 'react'
-import { Image, Text, View, type ImageSourcePropType } from 'react-native'
+import { type ComponentPropsWithRef, useState } from 'react'
+import { Image, type ImageSourcePropType, Text, View } from 'react-native'
 import type * as zyzz from 'zyzz'
 import { style, variants } from '../zyzz.config.js'
 

package/src/mobile/components/Button.tsx

@@ -1,6 +1,6 @@
 import * as Haptics from 'expo-haptics'
 import { cloneElement, type ComponentPropsWithRef, type ReactElement } from 'react'
-import { Pressable, Text, View, type ColorValue } from 'react-native'
+import { type ColorValue, Pressable, Text, View } from 'react-native'
 import type * as zyzz from 'zyzz'
 import { useColor } from '../internal/useColor.js'
 import { inverse } from '../vars.js'
@@ -58,7 +58,10 @@ export function Button(props: Button.Props) {
         styles.button({
           appearance,
           scale,
-          state: disabled ? 'disabled' : state.pressed ? 'pressed' : undefined,
+          state: (() => {
+            if (disabled) return 'disabled'
+            return state.pressed ? 'pressed' : undefined
+          })(),
           variant,
         }).style,
         typeof props.style === 'function' ? props.style(state) : props.style,

package/src/mobile/components/CodeInput.tsx

@@ -1,5 +1,5 @@
-import { useEffect, useImperativeHandle, useRef, useState, type ComponentPropsWithRef } from 'react'
-import { Keyboard, Text, TextInput, View, type StyleProp, type ViewStyle } from 'react-native'
+import { type ComponentPropsWithRef, useEffect, useImperativeHandle, useRef, useState } from 'react'
+import { Keyboard, type StyleProp, Text, TextInput, View, type ViewStyle } from 'react-native'
 import type * as zyzz from 'zyzz'
 import { style, variants } from '../zyzz.config.js'
 

package/src/mobile/components/IconButton.tsx

@@ -1,6 +1,6 @@
 import * as Haptics from 'expo-haptics'
 import { cloneElement, type ComponentPropsWithRef, type ReactElement } from 'react'
-import { Pressable, type ColorValue } from 'react-native'
+import { type ColorValue, Pressable } from 'react-native'
 import type * as zyzz from 'zyzz'
 import { useColor } from '../internal/useColor.js'
 import { inverse } from '../vars.js'
@@ -46,7 +46,10 @@ export function IconButton(props: IconButton.Props) {
         styles.button({
           appearance,
           scale,
-          state: disabled ? 'disabled' : state.pressed ? 'pressed' : undefined,
+          state: (() => {
+            if (disabled) return 'disabled'
+            return state.pressed ? 'pressed' : undefined
+          })(),
           variant,
         }).style,
         typeof props.style === 'function' ? props.style(state) : props.style,

package/src/mobile/components/Skeleton.tsx

@@ -1,5 +1,5 @@
 import type { ComponentPropsWithRef } from 'react'
-import { View, type DimensionValue } from 'react-native'
+import { type DimensionValue, View } from 'react-native'
 import Animated from 'react-native-reanimated'
 import type * as zyzz from 'zyzz'
 import { useReducedMotion } from '../internal/useReducedMotion.js'

package/src/mobile/components/Spinner.tsx

@@ -1,5 +1,5 @@
 import type { ComponentPropsWithRef } from 'react'
-import { View, type ColorValue } from 'react-native'
+import { type ColorValue, View } from 'react-native'
 import Animated from 'react-native-reanimated'
 import { Circle, Path, Svg } from 'react-native-svg'
 import type * as zyzz from 'zyzz'

package/src/mobile/components/TextButton.tsx

@@ -39,8 +39,12 @@ export function TextButton(props: TextButton.Props) {
         props.onPress?.(event)
       }}
       style={(state) => [
-        styles.button({ state: disabled ? 'disabled' : state.pressed ? 'pressed' : undefined })
-          .style,
+        styles.button({
+          state: (() => {
+            if (disabled) return 'disabled'
+            return state.pressed ? 'pressed' : undefined
+          })(),
+        }).style,
         typeof props.style === 'function' ? props.style(state) : props.style,
       ]}
     >

package/src/mobile/components/TextInput.tsx

@@ -1,5 +1,5 @@
 import type { ComponentPropsWithRef } from 'react'
-import { Text, TextInput as NativeTextInput, View } from 'react-native'
+import { TextInput as NativeTextInput, Text, View } from 'react-native'
 import type * as zyzz from 'zyzz'
 import { useColor } from '../internal/useColor.js'
 import { style, variants } from '../zyzz.config.js'

package/src/oxlint/index.ts

@@ -0,0 +1,89 @@
+/** Oxlint plugin and configurations that check how an app uses `@tempoxyz/ds`. @module */
+import type { Plugin } from '@oxlint/plugins'
+import * as NoCrossSurface from './rules/NoCrossSurface.ts'
+import * as NoInternalImports from './rules/NoInternalImports.ts'
+import * as NoRawValues from './rules/NoRawValues.ts'
+import * as PreferComponent from './rules/PreferComponent.ts'
+import * as RequireAccessibleName from './rules/RequireAccessibleName.ts'
+
+/** An Oxlint rule severity. */
+export type Severity = 'error' | 'off' | 'warn'
+
+/**
+ * A lint configuration that Oxlint and the `lint` option of Vite Plus accept. Arrays stay mutable
+ * because Oxlint's configuration type declares them mutable.
+ */
+export type Config = {
+  /** Plugins to load, keyed by the name that prefixes their rules. */
+  jsPlugins: { name: string; specifier: string }[]
+  /** Rule severities, with options as the second tuple member. */
+  rules: Record<string, Severity | [Severity, ...unknown[]]>
+}
+
+const plugins: Config['jsPlugins'] = [
+  { name: 'tds', specifier: '@tempoxyz/ds/oxlint' },
+  { name: 'zyzz', specifier: 'zyzz/oxlint' },
+]
+
+const zyzz: Config['rules'] = {
+  'zyzz/no-conflicting-props': 'error',
+  'zyzz/no-unused': 'warn',
+  'zyzz/valid-styles': 'error',
+}
+
+/**
+ * Enables the TDS and Zyzz rules for an app that renders `@tempoxyz/ds/mobile`.
+ *
+ * @example
+ * ```ts
+ * import { mobile } from '@tempoxyz/ds/oxlint'
+ *
+ * export default defineConfig({ lint: mobile })
+ * ```
+ */
+export const mobile: Config = {
+  jsPlugins: plugins,
+  rules: {
+    'tds/no-cross-surface': ['error', { surface: 'mobile' }],
+    'tds/no-internal-imports': 'error',
+    'tds/no-raw-values': 'warn',
+    'tds/require-accessible-name': 'error',
+    ...zyzz,
+  },
+}
+
+/**
+ * Enables the TDS and Zyzz rules for an app that renders `@tempoxyz/ds`.
+ *
+ * @example
+ * ```ts
+ * import { web } from '@tempoxyz/ds/oxlint'
+ *
+ * export default defineConfig({ lint: web })
+ * ```
+ */
+export const web: Config = {
+  jsPlugins: plugins,
+  rules: {
+    'tds/no-cross-surface': ['error', { surface: 'web' }],
+    'tds/no-internal-imports': 'error',
+    'tds/no-raw-values': 'warn',
+    'tds/prefer-component': 'warn',
+    'tds/require-accessible-name': 'error',
+    ...zyzz,
+  },
+}
+
+/** Register through `jsPlugins` as `tds`, then enable `tds/*` rules or spread `web` or `mobile`. */
+const plugin: Plugin = {
+  meta: { name: 'tds' },
+  rules: {
+    'no-cross-surface': NoCrossSurface.rule,
+    'no-internal-imports': NoInternalImports.rule,
+    'no-raw-values': NoRawValues.rule,
+    'prefer-component': PreferComponent.rule,
+    'require-accessible-name': RequireAccessibleName.rule,
+  },
+}
+
+export default plugin

package/src/oxlint/internal/Imports.ts

@@ -0,0 +1,68 @@
+/** Classifies `@tempoxyz/ds` import specifiers and visits every static module reference in a file. @module */
+import type { ESTree, Visitor } from '@oxlint/plugins'
+import * as Module from 'node:module'
+
+/** A library surface, named after the entrypoint that ships it. */
+export type Surface = 'mobile' | 'web'
+
+// The manifest sits three levels up from both `src/oxlint/internal` and `dist/oxlint/internal`.
+const manifest: { exports: Record<string, unknown>; name: string } = Module.createRequire(
+  import.meta.url,
+)('../../../package.json')
+
+/** The published package name, `@tempoxyz/ds`. */
+export const name = manifest.name
+
+/** Returns whether `source` names the package or one of its subpaths. */
+export function owned(source: string): boolean {
+  return source === name || source.startsWith(`${name}/`)
+}
+
+/** Returns whether `source` resolves through a subpath that the package `exports` map publishes. */
+export function published(source: string): boolean {
+  return owned(source) && Object.hasOwn(manifest.exports, `.${source.slice(name.length)}`)
+}
+
+/** Returns the surface a published specifier belongs to, or `undefined` for tooling entrypoints. */
+export function surface(source: string): Surface | undefined {
+  if (!published(source)) return undefined
+
+  const subpath = source.slice(name.length)
+
+  if (subpath === '/mobile' || subpath.startsWith('/mobile/')) return 'mobile'
+  if (subpath === '' || subpath.startsWith('/fonts/') || subpath.startsWith('/icons')) return 'web'
+  return undefined
+}
+
+/**
+ * Returns a visitor that calls `fn` with each string specifier in an import, a re-export, an
+ * `import()` expression, or an `import()` type.
+ */
+export function visit(fn: visit.Callback): Visitor {
+  function literal(node: ESTree.Node | null | undefined) {
+    if (node?.type === 'Literal' && typeof node.value === 'string') fn(node.value, node)
+  }
+
+  return {
+    ExportAllDeclaration(node) {
+      literal(node.source)
+    },
+    ExportNamedDeclaration(node) {
+      literal(node.source)
+    },
+    ImportDeclaration(node) {
+      literal(node.source)
+    },
+    ImportExpression(node) {
+      literal(node.source)
+    },
+    TSImportType(node) {
+      literal(node.source)
+    },
+  }
+}
+
+export declare namespace visit {
+  /** Receives the specifier and the string literal that spells it. */
+  type Callback = (source: string, node: ESTree.Node) => void
+}

package/src/oxlint/rules/NoCrossSurface.ts

@@ -0,0 +1,71 @@
+/** Keeps a file, or a whole app, on one `@tempoxyz/ds` surface. @module */
+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.
+ */
+export const rule: Rule = {
+  meta: {
+    docs: { description: 'Keep an app on one `@tempoxyz/ds` surface.' },
+    messages: {
+      configured:
+        "'{{source}}' belongs to the {{found}} surface, but this app uses the {{surface}} surface.",
+      mixed:
+        "'{{source}}' belongs to the {{found}} surface, but this file imports the {{surface}} surface.",
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: { surface: { enum: ['mobile', 'web'], type: 'string' } },
+        type: 'object',
+      },
+    ],
+    type: 'problem',
+  },
+  create(context) {
+    const options = context.options[0] as rule.Options | undefined
+
+    type Reference = { node: ESTree.Node; source: string; surface: Imports.Surface }
+
+    const references: Reference[] = []
+
+    return {
+      ...Imports.visit((source, node) => {
+        const surface = Imports.surface(source)
+
+        if (!surface) return
+        if (options?.surface && surface !== options.surface)
+          context.report({
+            data: { found: surface, source, surface: options.surface },
+            messageId: 'configured',
+            node,
+          })
+        references.push({ node, source, surface })
+      }),
+      'Program:exit'() {
+        if (options?.surface) return
+
+        const first = references[0]
+
+        if (!first) return
+        for (const reference of references)
+          if (reference.surface !== first.surface)
+            context.report({
+              data: { found: reference.surface, source: reference.source, surface: first.surface },
+              messageId: 'mixed',
+              node: reference.node,
+            })
+      },
+    }
+  },
+}
+
+export declare namespace rule {
+  /** Options for `tds/no-cross-surface`. */
+  type Options = {
+    /** The surface the app renders. When absent, the rule checks each file on its own. */
+    surface?: Imports.Surface | undefined
+  }
+}

package/src/oxlint/rules/NoInternalImports.ts

@@ -0,0 +1,25 @@
+/** Restricts `@tempoxyz/ds` imports to the subpaths that the package publishes. @module */
+import type { Rule } from '@oxlint/plugins'
+import * as Imports from '../internal/Imports.ts'
+
+/**
+ * Reports a `@tempoxyz/ds` specifier that the package `exports` map does not publish, such as
+ * `@tempoxyz/ds/src/web/components/Button`. Internal paths change without a release note.
+ */
+export const rule: Rule = {
+  meta: {
+    docs: { description: 'Allow only the published `@tempoxyz/ds` entrypoints.' },
+    messages: {
+      internal:
+        "'{{source}}' is not a published entrypoint. Import from '@tempoxyz/ds', '@tempoxyz/ds/mobile', or their `icons` subpaths.",
+    },
+    schema: [],
+    type: 'problem',
+  },
+  create(context) {
+    return Imports.visit((source, node) => {
+      if (Imports.owned(source) && !Imports.published(source))
+        context.report({ data: { source }, messageId: 'internal', node })
+    })
+  },
+}

package/src/oxlint/rules/NoRawValues.ts

@@ -0,0 +1,76 @@
+/** Finds raw colors, lengths, and font stacks in inline `style` props. @module */
+import type { ESTree, Rule } from '@oxlint/plugins'
+
+const color = /#[\da-f]{3,8}\b|\b(?:color|hsla?|hwb|lab|lch|oklab|oklch|rgba?)\(/i
+const length = /(?:^|[\s(,])-?(?:\d*\.)?\d+(?:em|pt|px|rem)\b/i
+
+// React and React Native read a bare number on these properties as pixels or points.
+const lengths =
+  /^(?:bottom|columnGap|end|flexBasis|fontSize|gap|height|inset\w*|left|margin\w*|maxHeight|maxWidth|minHeight|minWidth|padding\w*|right|rowGap|start|top|width|\w*Radius|\w*Width)$/
+
+/**
+ * Reports a color, length, or font family written as a literal in a JSX `style` prop. Values that
+ * read a custom property through `var()` pass, since they resolve to a token. Style values
+ * inside `style()` and `variants()` calls belong to `zyzz/valid-styles`.
+ */
+export const rule: Rule = {
+  meta: {
+    docs: { description: 'Use design tokens instead of raw values in inline styles.' },
+    messages: {
+      raw: "'{{property}}' sets the raw value {{value}}. Use a token through a Zyzz style instead.",
+    },
+    schema: [],
+    type: 'suggestion',
+  },
+  create(context) {
+    function raw(property: string, node: ESTree.Node) {
+      if (node.type === 'UnaryExpression' && node.operator === '-')
+        return raw(property, node.argument)
+      if (node.type === 'Literal' && typeof node.value === 'number')
+        return node.value !== 0 && lengths.test(property)
+      if (node.type === 'TemplateLiteral' && node.expressions.length === 0)
+        return text(property, node.quasis.map((quasi) => quasi.value.cooked ?? '').join(''))
+      if (node.type === 'Literal' && typeof node.value === 'string')
+        return text(property, node.value)
+      return false
+    }
+
+    function text(property: string, value: string) {
+      if (value.includes('var(')) return false
+      return property === 'fontFamily' || color.test(value) || length.test(value)
+    }
+
+    function check(node: ESTree.Node) {
+      if (node.type !== 'ObjectExpression') return
+      for (const property of node.properties) {
+        if (property.type !== 'Property' || property.computed) continue
+
+        const key = (() => {
+          if (property.key.type === 'Identifier') return property.key.name
+          if (property.key.type === 'Literal') return String(property.key.value)
+          return undefined
+        })()
+
+        if (key !== undefined && raw(key, property.value))
+          context.report({
+            data: { property: key, value: context.sourceCode.getText(property.value) },
+            messageId: 'raw',
+            node: property.value,
+          })
+      }
+    }
+
+    return {
+      JSXAttribute(node) {
+        if (node.name.type !== 'JSXIdentifier' || node.name.name !== 'style') return
+        if (node.value?.type !== 'JSXExpressionContainer') return
+
+        const expression = node.value.expression
+
+        if (expression.type === 'ArrayExpression')
+          for (const element of expression.elements) if (element) check(element)
+        check(expression)
+      },
+    }
+  },
+}

package/src/oxlint/rules/PreferComponent.ts

@@ -0,0 +1,113 @@
+/** Points native HTML controls and structures at the Web components that replace them. @module */
+import type { ESTree, Rule } from '@oxlint/plugins'
+
+// 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',
+  fieldset: 'Fieldset',
+  hr: 'Separator',
+  kbd: 'Kbd',
+  meter: 'Gauge',
+  progress: 'Progress',
+  select: 'Select',
+  table: 'Table',
+  textarea: 'Textarea',
+}
+
+// Input types without an entry, such as `file`, `hidden`, and `color`, have no replacement.
+const inputs: Record<string, string> = {
+  button: 'Button',
+  checkbox: 'Checkbox',
+  date: 'DatePicker',
+  email: 'Input',
+  number: 'NumberField',
+  password: 'Input',
+  radio: 'RadioGroup',
+  range: 'Slider',
+  reset: 'Button',
+  search: 'Input',
+  submit: 'Button',
+  tel: 'Input',
+  text: 'Input',
+  url: 'Input',
+}
+
+/**
+ * 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
+ * receives them supplies the styles.
+ */
+export const rule: Rule = {
+  meta: {
+    docs: {
+      description: 'Prefer `@tempoxyz/ds` components over the native elements they replace.',
+    },
+    messages: {
+      component: "Use '{{component}}' from '@tempoxyz/ds' instead of <{{element}}>.",
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: { allow: { items: { type: 'string' }, type: 'array' } },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+  create(context) {
+    const options = context.options[0] as rule.Options | undefined
+    const allow = new Set(options?.allow)
+
+    function component(node: ESTree.JSXOpeningElement) {
+      if (node.name.type !== 'JSXIdentifier') return undefined
+
+      const element = node.name.name
+
+      if (element !== 'input') return elements[element]
+
+      const type = node.attributes.find(
+        (attribute) =>
+          attribute.type === 'JSXAttribute' &&
+          attribute.name.type === 'JSXIdentifier' &&
+          attribute.name.name === 'type',
+      )
+
+      if (!type) return inputs.text
+      if (type.type !== 'JSXAttribute' || type.value?.type !== 'Literal') return undefined
+      return typeof type.value.value === 'string' ? inputs[type.value.value] : undefined
+    }
+
+    return {
+      JSXOpeningElement(node) {
+        if (node.name.type !== 'JSXIdentifier' || allow.has(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 replacement = component(node)
+
+        if (replacement)
+          context.report({
+            data: { component: replacement, element: node.name.name },
+            messageId: 'component',
+            node,
+          })
+      },
+    }
+  },
+}
+
+export declare namespace rule {
+  /** Options for `tds/prefer-component`. */
+  type Options = {
+    /** Element names to accept, such as `['table']` for a page that renders raw data. */
+    allow?: readonly string[] | undefined
+  }
+}