@setsquare/ui 0.1.0

package/dist/lint/index.js

@@ -0,0 +1,648 @@
+const RAC = 'react-aria-components';
+const PKG = '@setsquare/ui';
+/** React Aria components that render a VisuallyHidden input or button, and what to use instead. */
+const WRAPPED = {
+    Checkbox: 'Checkbox (or SelectionCheckbox in a Table or GridList)',
+    CheckboxGroup: 'CheckboxGroup',
+    Radio: 'Radio',
+    RadioGroup: 'RadioGroup',
+    Switch: 'Switch',
+    Slider: 'Slider or RangeSlider',
+    SliderTrack: 'Slider or RangeSlider',
+    SliderThumb: 'Slider or RangeSlider',
+    DateField: 'DateField',
+    TimeField: 'TimeField',
+    DatePicker: 'DatePicker',
+    DateRangePicker: 'DateRangePicker',
+    Calendar: 'Calendar',
+    RangeCalendar: 'RangeCalendar',
+    DropZone: 'FileUpload',
+    GridList: 'GridList',
+    GridListItem: 'GridListItem',
+};
+/** Also render hidden inputs, but have no Setsquare version yet. */
+const UNWRAPPED = ['ColorArea', 'ColorSlider', 'ColorWheel'];
+/** Setsquare components whose root must stay positioned. */
+const POSITIONED_ROOTS = new Set([
+    'Checkbox',
+    'CheckboxGroup',
+    'SelectionCheckbox',
+    'Radio',
+    'RadioGroup',
+    'Switch',
+    'Slider',
+    'RangeSlider',
+    'DateField',
+    'TimeField',
+    'DatePicker',
+    'DateRangePicker',
+    'Calendar',
+    'RangeCalendar',
+    'FileUpload',
+    'GridList',
+    'GridListItem',
+    'Table',
+    'ShellMain',
+    'SidebarContent',
+    'ListBox',
+    'Menu',
+    'TextField',
+    'TextArea',
+    'NumberField',
+    'Select',
+    'ComboBox',
+    'SearchField',
+]);
+/** Setsquare components whose `className` lands on the target (Layer 1). Their paint takes `visualClassName`. */
+const TARGET_COMPONENTS = new Set(['Button', 'LinkButton', 'IconButton', 'Segment']);
+/**
+ * min-h-* and min-w-* in a target's className replace the component's own min-h-target / min-w-target
+ * (tailwind-merge keeps the later of two classes for the same property), so they are the one way a className
+ * can take the target below --target-min. A height, width or max-* can't: min-width and min-height win.
+ */
+const TARGET_FLOOR = /^(?:[\w-]+:|\[[^\]]*\]:)*!?min-[hw]-.+$/;
+const DEFAULT_HELPERS = [
+    'cn',
+    'clsx',
+    'cx',
+    'classnames',
+    'classNames',
+    'twMerge',
+    'twJoin',
+    'cva',
+    'tv',
+];
+const SCROLL = /^(?:[\w-]+:|\[[^\]]*\]:)*!?overflow-(?:x-|y-)?(?:auto|scroll)!?$/;
+const POSITIONED = /^(?:[\w-]+:|\[[^\]]*\]:)*!?(?:relative|absolute|fixed|sticky)!?$/;
+const STATIC = /^(?:[\w-]+:|\[[^\]]*\]:)*!?static!?$/;
+const tokens = (s) => s.split(/\s+/).filter(Boolean);
+/** Every string that can end up in a class list: literals, template text, helper arguments, both branches of ?: and &&. */
+function collectClassStrings(expr, helpers, out = []) {
+    if (!expr)
+        return out;
+    switch (expr.type) {
+        case 'Literal':
+            if (typeof expr.value === 'string')
+                out.push({ node: expr, text: expr.value });
+            break;
+        case 'TemplateLiteral':
+            for (const q of expr.quasis)
+                out.push({
+                    node: q,
+                    text: String(q.value.cooked ??
+                        q.value.raw),
+                });
+            for (const e of expr.expressions)
+                collectClassStrings(e, helpers, out);
+            break;
+        case 'JSXExpressionContainer':
+            collectClassStrings(expr.expression, helpers, out);
+            break;
+        case 'ConditionalExpression':
+            collectClassStrings(expr.consequent, helpers, out);
+            collectClassStrings(expr.alternate, helpers, out);
+            break;
+        case 'LogicalExpression':
+            collectClassStrings(expr.left, helpers, out);
+            collectClassStrings(expr.right, helpers, out);
+            break;
+        case 'ArrayExpression':
+            for (const e of expr.elements)
+                collectClassStrings(e, helpers, out);
+            break;
+        case 'ObjectExpression':
+            // clsx({ 'overflow-auto': cond }) — the keys are the classes.
+            for (const p of expr.properties) {
+                if (p.type === 'Property') {
+                    const key = p.key;
+                    if (key.type === 'Literal' && typeof key.value === 'string')
+                        out.push({ node: key, text: key.value });
+                    else if (key.type === 'Identifier' && !p.computed)
+                        out.push({ node: key, text: String(key.name) });
+                    collectClassStrings(p.value, helpers, out);
+                }
+            }
+            break;
+        case 'CallExpression': {
+            const callee = expr.callee;
+            const name = callee.type === 'Identifier'
+                ? String(callee.name)
+                : callee.type === 'MemberExpression'
+                    ? String(callee.property.name)
+                    : '';
+            if (helpers.has(name))
+                for (const a of expr.arguments)
+                    collectClassStrings(a, helpers, out);
+            break;
+        }
+        case 'TSAsExpression':
+        case 'TSSatisfiesExpression':
+        case 'TSNonNullExpression':
+            collectClassStrings(expr.expression, helpers, out);
+            break;
+        default:
+            break;
+    }
+    return out;
+}
+function attr(opening, name) {
+    return opening.attributes.find((a) => a.type === 'JSXAttribute' &&
+        a.name.type === 'JSXIdentifier' &&
+        a.name.name === name);
+}
+/** overflow / overflowX / overflowY: 'auto' | 'scroll' in an inline style object, and whether it sets position. */
+function styleScroll(styleAttr) {
+    const value = styleAttr?.value;
+    const obj = value?.type === 'JSXExpressionContainer' ? value.expression : null;
+    if (!obj || obj.type !== 'ObjectExpression')
+        return { scrolls: null, positioned: false };
+    let scrolls = null;
+    let positioned = false;
+    for (const p of obj.properties) {
+        if (p.type !== 'Property')
+            continue;
+        const key = p.key;
+        const k = key.type === 'Identifier' ? key.name : key.type === 'Literal' ? key.value : null;
+        const v = p.value;
+        if ((k === 'overflow' || k === 'overflowX' || k === 'overflowY') &&
+            v.type === 'Literal' &&
+            (v.value === 'auto' || v.value === 'scroll'))
+            scrolls = p;
+        if (k === 'position' &&
+            v.type === 'Literal' &&
+            ['relative', 'absolute', 'fixed', 'sticky'].includes(String(v.value)))
+            positioned = true;
+    }
+    return { scrolls, positioned };
+}
+/**
+ * Where `relative ` can go without changing any other class: the start of a string literal, or the start of a
+ * template literal (straight after the backtick). The string holding the overflow class is preferred.
+ */
+function fixTarget(preferred, all, source) {
+    const start = (s) => {
+        const range = s.node.range;
+        if (!range)
+            return null;
+        if (s.node.type === 'Literal')
+            return range[0] + 1;
+        if (s.node.type === 'TemplateElement' && source.text[range[0]] === '`')
+            return range[0] + 1;
+        return null;
+    };
+    for (const s of [preferred, ...all]) {
+        const at = start(s);
+        if (at != null)
+            return at;
+    }
+    return null;
+}
+const positionedScrollContainer = {
+    meta: {
+        type: 'problem',
+        fixable: 'code',
+        docs: {
+            description: 'Require every scroll container to be positioned, so absolutely positioned descendants scroll with it',
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: { helpers: { type: 'array', items: { type: 'string' } } },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            missing: "'{{cls}}' makes this a scroll container, but it isn't positioned. Add 'relative': otherwise sr-only text and React Aria's hidden inputs inside it are placed against an outer element, don't scroll with the content, and shift the page when they are focused or read.",
+            missingStyle: "This inline style makes the element a scroll container, but it isn't positioned. Add position: 'relative' (or the 'relative' class) so absolutely positioned descendants scroll with it.",
+        },
+    },
+    create(context) {
+        const opts = (context.options[0] ?? {});
+        const helpers = new Set(opts.helpers ?? DEFAULT_HELPERS);
+        const check = (strings, reportOn) => {
+            const all = strings.flatMap((s) => tokens(s.text).map((t) => ({ t, s })));
+            const scroll = all.find((x) => SCROLL.test(x.t));
+            if (!scroll || all.some((x) => POSITIONED.test(x.t)))
+                return;
+            context.report({
+                node: (scroll.s.node ?? reportOn),
+                messageId: 'missing',
+                data: { cls: scroll.t },
+                fix: (fixer) => {
+                    const at = fixTarget(scroll.s, strings, context.sourceCode);
+                    return at == null ? null : fixer.insertTextBeforeRange([at, at], 'relative ');
+                },
+            });
+        };
+        return {
+            JSXOpeningElement(node) {
+                const n = node;
+                const classAttr = attr(n, 'className') ?? attr(n, 'class');
+                const strings = classAttr ? collectClassStrings(classAttr.value, helpers) : [];
+                const style = styleScroll(attr(n, 'style'));
+                const classPositioned = strings.some((s) => tokens(s.text).some((t) => POSITIONED.test(t)));
+                if (style.scrolls && !style.positioned && !classPositioned) {
+                    context.report({
+                        node: style.scrolls,
+                        messageId: 'missingStyle',
+                    });
+                    return;
+                }
+                if (style.positioned)
+                    return;
+                if (strings.length)
+                    check(strings, n);
+            },
+            CallExpression(node) {
+                const n = node;
+                // Inside a className attribute, the JSX handler checks the whole attribute as one class list.
+                for (let p = n.parent; p; p = p.parent) {
+                    if (p.type === 'JSXAttribute' &&
+                        ['className', 'class'].includes(String(p.name.name)))
+                        return;
+                    if (p.type === 'JSXOpeningElement' || p.type === 'Program')
+                        break;
+                }
+                const callee = n.callee;
+                const name = callee.type === 'Identifier' ? String(callee.name) : '';
+                if (!helpers.has(name))
+                    return;
+                // Only the outermost helper call is one class list.
+                const parent = n.parent;
+                if (parent?.type === 'CallExpression' &&
+                    helpers.has(String(parent.callee?.name)))
+                    return;
+                const strings = collectClassStrings(n, helpers);
+                if (name === 'cva' || name === 'tv') {
+                    // Variant helpers: each variant string is applied on its own, so check the base alone and each string.
+                    const base = collectClassStrings(n.arguments[0], helpers);
+                    if (base.length)
+                        check(base, n);
+                    return;
+                }
+                check(strings, n);
+            },
+        };
+    },
+};
+const noRawAriaControls = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: "Use @setsquare/ui's versions of React Aria components that render a visually hidden input",
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: { allow: { type: 'array', items: { type: 'string' } } },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            wrapped: "Use {{replacement}} from '@setsquare/ui' instead of React Aria's {{name}}. React Aria renders its input in a visually hidden, absolutely positioned span; the Setsquare version keeps a positioned root so the page doesn't shift when it is focused, and brings the conformance tokens with it.",
+            unwrapped: "React Aria's {{name}} renders a visually hidden, absolutely positioned input and has no Setsquare version yet. Give its root 'relative', then add it to this rule's allow list.",
+        },
+    },
+    create(context) {
+        const opts = (context.options[0] ?? {});
+        const allow = new Set(opts.allow ?? []);
+        const namespaces = new Set();
+        const report = (node, name) => {
+            if (allow.has(name))
+                return;
+            if (WRAPPED[name])
+                context.report({
+                    node: node,
+                    messageId: 'wrapped',
+                    data: { name, replacement: WRAPPED[name] },
+                });
+            else if (UNWRAPPED.includes(name))
+                context.report({
+                    node: node,
+                    messageId: 'unwrapped',
+                    data: { name },
+                });
+        };
+        const importedName = (s) => {
+            const imp = s.imported;
+            return imp ? String(imp.type === 'Literal' ? imp.value : imp.name) : '';
+        };
+        return {
+            ImportDeclaration(node) {
+                const n = node;
+                if (n.source.value !== RAC || n.importKind === 'type')
+                    return;
+                for (const s of n.specifiers) {
+                    if (s.type === 'ImportSpecifier' && s.importKind !== 'type')
+                        report(s, importedName(s));
+                    if (s.type === 'ImportNamespaceSpecifier')
+                        namespaces.add(String(s.local.name));
+                }
+            },
+            ExportNamedDeclaration(node) {
+                const n = node;
+                if (n.source?.value !== RAC || n.exportKind === 'type')
+                    return;
+                for (const s of n.specifiers) {
+                    const local = s.local;
+                    report(s, String(local.type === 'Literal' ? local.value : local.name));
+                }
+            },
+            JSXMemberExpression(node) {
+                const n = node;
+                const obj = n.object;
+                if (obj.type === 'JSXIdentifier' && namespaces.has(String(obj.name)))
+                    report(n, String(n.property.name));
+            },
+            MemberExpression(node) {
+                const n = node;
+                const obj = n.object;
+                if (obj.type === 'Identifier' && namespaces.has(String(obj.name)) && !n.computed)
+                    report(n, String(n.property.name));
+            },
+        };
+    },
+};
+const noStaticControlRoot = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow `static` on @setsquare/ui components whose root must stay positioned',
+        },
+        schema: [],
+        messages: {
+            static: "'{{cls}}' removes the positioning {{name}} depends on: its root is 'relative' so React Aria's hidden input (or the sr-only text inside it) stays with it. Remove '{{cls}}'.",
+        },
+    },
+    create(context) {
+        const local = new Map();
+        return {
+            ImportDeclaration(node) {
+                const n = node;
+                const src = String(n.source.value);
+                if (src !== PKG && !src.startsWith(`${PKG}/`))
+                    return;
+                for (const s of n.specifiers) {
+                    if (s.type !== 'ImportSpecifier')
+                        continue;
+                    const imp = s.imported;
+                    const name = String(imp.type === 'Literal' ? imp.value : imp.name);
+                    if (POSITIONED_ROOTS.has(name))
+                        local.set(String(s.local.name), name);
+                }
+            },
+            JSXOpeningElement(node) {
+                const n = node;
+                const nameNode = n.name;
+                if (nameNode.type !== 'JSXIdentifier' || !local.has(String(nameNode.name)))
+                    return;
+                const classAttr = attr(n, 'className');
+                if (!classAttr)
+                    return;
+                for (const s of collectClassStrings(classAttr.value, new Set(DEFAULT_HELPERS))) {
+                    const hit = tokens(s.text).find((t) => STATIC.test(t));
+                    if (hit)
+                        context.report({
+                            node: s.node,
+                            messageId: 'static',
+                            data: { cls: hit, name: local.get(String(nameNode.name)) },
+                        });
+                }
+            },
+        };
+    },
+};
+/** The imported names of @setsquare/ui components in this file, local name → exported name. */
+function trackPackageImports(local, wanted) {
+    return (node) => {
+        const n = node;
+        const src = String(n.source.value);
+        if (src !== PKG && !src.startsWith(`${PKG}/`))
+            return;
+        for (const s of n.specifiers) {
+            if (s.type !== 'ImportSpecifier')
+                continue;
+            const imp = s.imported;
+            const name = String(imp.type === 'Literal' ? imp.value : imp.name);
+            if (wanted.has(name))
+                local.set(String(s.local.name), name);
+        }
+    };
+}
+const noTargetShrink = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow min-h-* and min-w-* in the className of a three-layer control: it is the target, and they replace its --target-min floor',
+        },
+        schema: [],
+        messages: {
+            shrink: "'{{cls}}' is on {{name}}'s target (Layer 1), the element a pointer has to hit, and replaces its --target-min floor: at AAA the target could be smaller than 44px. Size the painted box with visualSize, or put the class on visualClassName.",
+        },
+    },
+    create(context) {
+        const local = new Map();
+        return {
+            ImportDeclaration: trackPackageImports(local, TARGET_COMPONENTS),
+            JSXOpeningElement(node) {
+                const n = node;
+                const nameNode = n.name;
+                if (nameNode.type !== 'JSXIdentifier' || !local.has(String(nameNode.name)))
+                    return;
+                const classAttr = attr(n, 'className');
+                if (!classAttr)
+                    return;
+                for (const s of collectClassStrings(classAttr.value, new Set(DEFAULT_HELPERS))) {
+                    const hit = tokens(s.text).find((t) => TARGET_FLOOR.test(t));
+                    if (hit)
+                        context.report({
+                            node: s.node,
+                            messageId: 'shrink',
+                            data: { cls: hit, name: local.get(String(nameNode.name)) },
+                        });
+                }
+            },
+        };
+    },
+};
+/** Does this expression call `name(…)` anywhere inside it? */
+function callsFunction(expr, name) {
+    if (!expr || typeof expr !== 'object')
+        return false;
+    if (expr.type === 'CallExpression' &&
+        expr.callee.type === 'Identifier' &&
+        expr.callee.name === name)
+        return true;
+    for (const [key, value] of Object.entries(expr)) {
+        if (key === 'parent' || key === 'loc' || key === 'range')
+            continue;
+        if (Array.isArray(value)) {
+            if (value.some((v) => v && typeof v === 'object' && callsFunction(v, name)))
+                return true;
+        }
+        else if (value && typeof value === 'object' && 'type' in value) {
+            if (callsFunction(value, name))
+                return true;
+        }
+    }
+    return false;
+}
+/** <a>, <button>, and components named like links and buttons (Link, NextLink, RACButton, ToggleButton…). */
+function isInteractiveElement(nameNode) {
+    const name = nameNode.type === 'JSXIdentifier'
+        ? String(nameNode.name)
+        : nameNode.type === 'JSXMemberExpression'
+            ? String(nameNode.property.name)
+            : '';
+    if (name === 'a' || name === 'button')
+        return name;
+    if (/(?:Link|Button)$/.test(name))
+        return name;
+    return null;
+}
+const noVisualOnlyTarget = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow buttonVisualStyles() on an interactive element: it is the painted box, and on its own it makes the paint the pointer target',
+        },
+        schema: [],
+        messages: {
+            visualOnly: 'buttonVisualStyles() paints Layer 2 only. On <{{name}}> it makes the painted box the pointer target, so a small button is a small target and fails 2.5.5 at AAA. Put buttonTargetStyles() on <{{name}}> and buttonVisualStyles() on a span inside it, or use LinkButton.',
+        },
+    },
+    create(context) {
+        return {
+            JSXOpeningElement(node) {
+                const n = node;
+                const name = isInteractiveElement(n.name);
+                if (!name)
+                    return;
+                const classAttr = attr(n, 'className');
+                if (!classAttr)
+                    return;
+                if (callsFunction(classAttr.value, 'buttonVisualStyles'))
+                    context.report({
+                        node: classAttr,
+                        messageId: 'visualOnly',
+                        data: { name },
+                    });
+            },
+        };
+    },
+};
+/** Hooks React's server build exports (react.react-server in React 19): a server component may call these. */
+const SERVER_HOOKS = new Set(['use', 'useCallback', 'useDebugValue', 'useId', 'useMemo']);
+/** Packages that only work in the client graph: React Aria's entry imports `client-only`. */
+const CLIENT_PACKAGES = /^(react-aria-components|react-aria|react-stately|@react-aria\/|@react-stately\/)/;
+const clientDirective = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: "Require 'use client' exactly when a module needs it: React Aria, a hook, a context, an event handler or a function passed as a prop",
+        },
+        schema: [],
+        messages: {
+            missing: "This module {{reason}}, which only a client module can do. Add 'use client' as its first line.",
+            unneeded: "'use client' isn't needed here: nothing in this module needs the client (React Aria, a hook other than use, useCallback, useDebugValue, useId or useMemo, createContext, an event handler, or a function passed as a prop or child). Remove it, so server components can use this module without shipping it to the browser.",
+        },
+    },
+    create(context) {
+        let directive = null;
+        let reason = null;
+        const need = (node, text) => {
+            reason ??= { node, text };
+        };
+        const isFunction = (n) => !!n && (n.type === 'ArrowFunctionExpression' || n.type === 'FunctionExpression');
+        return {
+            Program(node) {
+                // The directive prologue: string-literal statements at the very start of the file.
+                for (const stmt of node.body) {
+                    const expr = stmt.expression;
+                    if (stmt.type !== 'ExpressionStatement' || expr?.type !== 'Literal')
+                        break;
+                    if (typeof expr.value === 'string' && expr.value === 'use client')
+                        directive = stmt;
+                }
+            },
+            ImportDeclaration(node) {
+                const n = node;
+                if (n.importKind === 'type')
+                    return;
+                const source = String(n.source.value);
+                const specifiers = n.specifiers ?? [];
+                const valueImport = !specifiers.length || specifiers.some((s) => s.importKind !== 'type');
+                if (CLIENT_PACKAGES.test(source) && valueImport)
+                    need(n, `imports ${source}`);
+            },
+            CallExpression(node) {
+                const n = node;
+                const callee = n.callee;
+                const name = callee.type === 'Identifier'
+                    ? String(callee.name)
+                    : callee.type === 'MemberExpression' &&
+                        callee.property.type === 'Identifier'
+                        ? String(callee.property.name)
+                        : '';
+                if (name === 'createContext')
+                    need(n, 'creates a context');
+                else if (/^use[A-Z]/.test(name) && !SERVER_HOOKS.has(name))
+                    need(n, `calls ${name}`);
+            },
+            JSXAttribute(node) {
+                const n = node;
+                const attrName = String(n.name.name);
+                const value = n.value;
+                const expr = value?.type === 'JSXExpressionContainer' ? value.expression : null;
+                if (/^on[A-Z]/.test(attrName))
+                    need(n, `passes an event handler (${attrName})`);
+                else if (isFunction(expr))
+                    need(n, `passes a function as a prop (${attrName})`);
+            },
+            JSXExpressionContainer(node) {
+                const n = node;
+                if (n.parent?.type === 'JSXAttribute')
+                    return;
+                if (isFunction(n.expression))
+                    need(n, 'passes a function as a child');
+            },
+            'Program:exit'() {
+                if (reason && !directive)
+                    context.report({
+                        node: reason.node,
+                        messageId: 'missing',
+                        data: { reason: reason.text },
+                    });
+                else if (directive && !reason)
+                    context.report({ node: directive, messageId: 'unneeded' });
+            },
+        };
+    },
+};
+export const rules = {
+    'no-raw-aria-controls': noRawAriaControls,
+    'positioned-scroll-container': positionedScrollContainer,
+    'no-static-control-root': noStaticControlRoot,
+    'no-target-shrink': noTargetShrink,
+    'no-visual-only-target': noVisualOnlyTarget,
+    'client-directive': clientDirective,
+};
+const plugin = {
+    meta: { name: '@setsquare/ui/lint' },
+    rules,
+    configs: {},
+};
+/** Flat config: `import setsquare from '@setsquare/ui/lint'; export default [setsquare.configs.recommended]`. */
+plugin.configs.recommended = {
+    name: 'setsquare-ui/recommended',
+    plugins: { 'setsquare-ui': plugin },
+    rules: {
+        'setsquare-ui/no-raw-aria-controls': 'error',
+        'setsquare-ui/positioned-scroll-container': 'error',
+        'setsquare-ui/no-static-control-root': 'error',
+        'setsquare-ui/no-target-shrink': 'error',
+        'setsquare-ui/no-visual-only-target': 'error',
+    },
+};
+export default plugin;
+//# sourceMappingURL=index.js.map