diff --git a/.oxfmtrc.json b/.oxfmtrc.json index 92d1e75c0f3..a4e890ecb22 100644 --- a/.oxfmtrc.json +++ b/.oxfmtrc.json @@ -9,5 +9,12 @@ "bracketSpacing": false, "trailingComma": "none", "bracketSameLine": true, - "arrowParens": "avoid" + "arrowParens": "avoid", + "jsdoc": { + "addDefaultToDescription": false, + "capitalizeDescriptions": true, + "commentLineStrategy": "keep", + "descriptionWithDot": true, + "lineWrappingStyle": "balance" + } } diff --git a/.oxlintrc.json b/.oxlintrc.json new file mode 100644 index 00000000000..70c61a932a3 --- /dev/null +++ b/.oxlintrc.json @@ -0,0 +1,391 @@ +{ + "$schema": "./node_modules/oxlint/configuration_schema.json", + "plugins": ["react", "jsx-a11y"], + "jsPlugins": [ + "eslint-plugin-rsp-rules", + { + "name": "monorepo", + "specifier": "@jdb8/eslint-plugin-monorepo" + }, + { + "name": "react-hooks-js", + "specifier": "eslint-plugin-react-hooks" + } + ], + "categories": { + "correctness": "off" + }, + "env": { + "builtin": true, + "browser": true, + "node": true, + "es6": true, + "commonjs": true, + "mocha": true, + "jest": true + }, + "globals": { + "importSpectrumCSS": "readonly", + "JSX": "readonly", + "NodeJS": "readonly", + "AsyncIterable": "readonly", + "FileSystemFileEntry": "readonly", + "FileSystemDirectoryEntry": "readonly", + "FileSystemEntry": "readonly", + "IS_REACT_ACT_ENVIRONMENT": "readonly" + }, + "settings": { + "jsdoc": { + "ignorePrivate": true, + "publicFunctionsOnly": true + }, + "react": { + "version": "18.3.1" + } + }, + "ignorePatterns": [ + "packages/@react-aria/i18n/server", + "packages/@spectrum-icons/color/**/*", + "packages/@spectrum-icons/ui/**/*", + "packages/@spectrum-icons/workflow/**/*", + "packages/@spectrum-icons/illustrations/**/*", + "packages/@spectrum-icons/express/**/*", + "**/node_modules", + "packages/*/*/dist", + "packages/*/*/i18n", + "packages/react-aria/dist", + "packages/react-aria/i18n", + "packages/react-aria-components/dist", + "packages/react-aria-components/i18n", + "packages/react-stately/dist", + "packages/dev/storybook-builder-parcel/preview.js", + "packages/dev/optimize-locales-plugin/LocalesPlugin.d.ts", + "examples/**/*", + "starters/**/*", + "scripts/icon-builder-fixture/**/*", + "packages/@react-spectrum/s2/icon.d.ts", + "packages/@react-spectrum/s2/spectrum-illustrations", + "packages/dev/parcel-config-storybook/*", + "packages/dev/parcel-resolver-storybook/*", + "packages/dev/parcel-transformer-storybook/*", + "packages/dev/storybook-builder-parcel/*", + "packages/dev/storybook-react-parcel/*", + "packages/dev/s2-docs/pages/**", + "packages/dev/mcp/*/dist", + "packages/dev/codemods/src/s1-to-s2/__testfixtures__/cli/**" + ], + "rules": { + // eslint recommended rules + "constructor-super": "error", + "for-direction": "error", + "getter-return": "error", + "no-async-promise-executor": "error", + "no-case-declarations": "error", + "no-class-assign": "error", + "no-compare-neg-zero": "error", + "no-cond-assign": "error", + "no-const-assign": "error", + "no-constant-binary-expression": "error", + "no-constant-condition": "error", + "no-control-regex": "error", + "no-debugger": "error", + "no-delete-var": "error", + "no-dupe-class-members": "error", + "no-dupe-else-if": "error", + "no-dupe-keys": "error", + "no-duplicate-case": "error", + "no-empty": "error", + "no-empty-character-class": "error", + "no-empty-pattern": "error", + "no-empty-static-block": "error", + "no-ex-assign": "error", + "no-extra-boolean-cast": "error", + "no-func-assign": "error", + "no-global-assign": "error", + "no-import-assign": "error", + "no-invalid-regexp": "error", + "no-irregular-whitespace": ["error"], + "no-loss-of-precision": "error", + "no-misleading-character-class": "error", + "no-new-native-nonconstructor": "error", + "no-nonoctal-decimal-escape": "error", + "no-obj-calls": "error", + "no-prototype-builtins": "error", + "no-redeclare": [ + "error", + { + "builtinGlobals": false + } + ], + "no-regex-spaces": "error", + "no-self-assign": "error", + "no-setter-return": "error", + "no-shadow-restricted-names": "error", + "no-sparse-arrays": "error", + "no-this-before-super": "error", + "no-unexpected-multiline": "error", + "no-unreachable": "error", + "no-unsafe-finally": "error", + "no-unsafe-negation": "error", + "no-unsafe-optional-chaining": "error", + "no-unused-labels": "error", + "no-unused-vars": [ + "error", + { + "args": "none", + "vars": "all", + "varsIgnorePattern": "[rR]eact" + } + ], + "no-useless-backreference": "error", + "no-useless-catch": "error", + "no-useless-escape": "error", + "no-with": "error", + "require-yield": "error", + "use-isnan": "error", + "valid-typeof": "error", + // custom rules + "eqeqeq": ["error", "smart"], + "max-depth": ["warn", 4], + "radix": ["error", "always"], + "no-new-wrappers": "error", + "no-self-compare": "error", + "no-nested-ternary": "off", + "no-unneeded-ternary": "error", + "react/jsx-no-duplicate-props": "error", + "react/jsx-no-undef": "error", + "react/no-did-update-set-state": "error", + "react/no-unknown-property": [ + "error", + { + "ignore": ["prefix"] + } + ], + "react/react-in-jsx-scope": "error", + "react/jsx-boolean-value": "error", + "react/self-closing-comp": "error", + + // Core hooks rules + "react/rules-of-hooks": "error", + "react/exhaustive-deps": "warn", + + // React Compiler rules + "react-hooks-js/config": "error", + "react-hooks-js/error-boundaries": "error", + "react-hooks-js/component-hook-factories": "error", + "react-hooks-js/gating": "error", + "react-hooks-js/globals": "error", + "react-hooks-js/purity": "error", + "react-hooks-js/set-state-in-effect": "warn", + "react-hooks-js/set-state-in-render": "error", + "react-hooks-js/static-components": "error", + "react-hooks-js/unsupported-syntax": "warn", + "react-hooks-js/use-memo": "error", + "react-hooks-js/incompatible-library": "warn", + + "rsp-rules/no-react-key": ["error"], + "rsp-rules/sort-imports": ["error"], + "rsp-rules/no-non-shadow-contains": ["error"], + "rsp-rules/safe-event-target": ["error"], + "rsp-rules/shadow-safe-active-element": ["error"], + "rsp-rules/faster-node-contains": ["error"], + "rsp-rules/imports": ["error"], + "rsp-rules/use-layout-effect-rule": ["error"], + "rsp-rules/pure-render": ["error"], + "jsx-a11y/alt-text": "error", + "jsx-a11y/anchor-has-content": "error", + "jsx-a11y/anchor-is-valid": "error", + "jsx-a11y/aria-activedescendant-has-tabindex": "error", + "jsx-a11y/aria-props": "error", + "jsx-a11y/aria-proptypes": "error", + "jsx-a11y/aria-role": "error", + "jsx-a11y/aria-unsupported-elements": "error", + "jsx-a11y/click-events-have-key-events": "error", + "jsx-a11y/heading-has-content": "error", + "jsx-a11y/html-has-lang": "error", + "jsx-a11y/iframe-has-title": "error", + "jsx-a11y/img-redundant-alt": "error", + "jsx-a11y/interactive-supports-focus": [ + "error", + { + "tabbable": ["button", "checkbox", "link", "searchbox", "spinbutton", "switch", "textbox"] + } + ], + "jsx-a11y/label-has-associated-control": [ + "error", + { + "assert": "either", + "depth": 3 + } + ], + "jsx-a11y/media-has-caption": "error", + "jsx-a11y/mouse-events-have-key-events": "error", + "jsx-a11y/no-access-key": "error", + "jsx-a11y/no-distracting-elements": "error", + "jsx-a11y/no-noninteractive-tabindex": [ + "error", + { + "tags": [], + "roles": ["alertdialog", "dialog", "tabpanel"] + } + ], + "jsx-a11y/no-redundant-roles": "error", + "jsx-a11y/no-static-element-interactions": [ + "error", + { + "handlers": ["onClick", "onMouseDown", "onMouseUp", "onKeyPress", "onKeyDown", "onKeyUp"] + } + ], + "jsx-a11y/role-has-required-aria-props": "error", + "jsx-a11y/role-supports-aria-props": "error", + "jsx-a11y/scope": "error", + "jsx-a11y/tabindex-no-positive": "error", + "monorepo/no-relative-import": "error" + }, + "overrides": [ + { + "files": ["packages/**/*.ts", "packages/**/*.tsx"], + "rules": { + "jsdoc/check-tag-names": [ + "error", + { + "definedTags": ["selector", "note"] + } + ], + "no-unused-vars": "error" + }, + "globals": { + "globalThis": "readonly" + }, + "plugins": ["jsdoc", "typescript"] + }, + { + "files": [ + "packages/@*/**/src/**/*.ts", + "packages/@*/**/src/**/*.tsx", + "packages/react-*/**/src/**/*.ts", + "packages/react-*/**/src/**/*.tsx", + "packages/tailwindcss-react-aria-components/**/*.ts", + "packages/tailwindcss-react-aria-components/**/*.tsx" + ], + "rules": { + "rsp-rules/no-package-root-imports": "error" + } + }, + { + "files": [ + "**/test/**", + "**/stories/**", + "**/docs/**", + "**/chromatic/**", + "**/chromatic-fc/**", + "**/__tests__/**" + ], + "rules": { + "rsp-rules/no-react-key": ["error"], + "rsp-rules/act-events-test": "error", + "rsp-rules/no-getByRole-toThrow": "error", + "rsp-rules/no-non-shadow-contains": "off", + "rsp-rules/safe-event-target": "off", + "rsp-rules/shadow-safe-active-element": "off", + "rsp-rules/faster-node-contains": "off", + "rsp-rules/imports": "off", + "monorepo/no-internal-import": "off", + "react/react-in-jsx-scope": "off", + "jsx-a11y/interactive-supports-focus": "off" + }, + "globals": { + "importSpectrumCSS": "readonly", + "JSX": "readonly", + "NodeJS": "readonly", + "AsyncIterable": "readonly", + "FileSystemFileEntry": "readonly", + "FileSystemDirectoryEntry": "readonly", + "FileSystemEntry": "readonly", + "IS_REACT_ACT_ENVIRONMENT": "readonly", + "globalThis": "readonly" + }, + "env": { + "builtin": true, + "browser": true, + "node": true, + "es6": true, + "commonjs": true, + "mocha": true, + "jest": true + } + }, + { + "files": ["**/dev/**", "**/scripts/**"], + "rules": { + "rsp-rules/safe-event-target": "off" + } + }, + { + "files": [ + "packages/@react-aria/focus/src/**/*.ts", + "packages/@react-aria/focus/src/**/*.tsx" + ], + "rules": { + "no-restricted-globals": [ + "error", + { + "name": "window", + "message": "Use getOwnerWindow from @react-aria/utils instead." + }, + { + "name": "document", + "message": "Use getOwnerDocument from @react-aria/utils instead." + } + ] + } + }, + { + "files": [ + "packages/react-aria/src/interactions/**/*.ts", + "packages/react-aria/src/interactions/**/*.tsx" + ], + "rules": { + "no-restricted-globals": [ + "warn", + { + "name": "window", + "message": "Use getOwnerWindow from @react-aria/utils instead." + }, + { + "name": "document", + "message": "Use getOwnerDocument from @react-aria/utils instead." + } + ] + } + }, + { + "files": [ + "packages/@react-aria/test-utils/src/**/*.ts", + "packages/@react-aria/test-utils/src/**/*.tsx" + ], + "rules": { + "rsp-rules/faster-node-contains": "off", + "rsp-rules/no-non-shadow-contains": "off", + "rsp-rules/shadow-safe-active-element": "off" + } + }, + { + "files": ["packages/@react-spectrum/s2/**", "packages/dev/s2-docs/**"], + "rules": { + "react/react-in-jsx-scope": "off" + } + }, + { + "files": ["packages/dev/style-macro-chrome-plugin/**"], + "env": { + "builtin": true, + "browser": true, + "webextensions": true, + "node": true, + "es6": true, + "commonjs": true + } + } + ] +} diff --git a/.storybook-s2/custom-addons/provider/preset.ts b/.storybook-s2/custom-addons/provider/preset.ts index fafbb22081c..a8d04cba4ae 100644 --- a/.storybook-s2/custom-addons/provider/preset.ts +++ b/.storybook-s2/custom-addons/provider/preset.ts @@ -8,6 +8,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url)); * The manager builder will bundle register.tsx and transpile JSX there; * this file stays JS-free so Node can load it as a preset. * In plain english, this is needed so that register can be a tsx file. + * * @see https://github.com/storybookjs/addon-kit * @see https://storybook.js.org/docs/addons/writing-presets#managerentries */ diff --git a/.storybook-s2/preview.tsx b/.storybook-s2/preview.tsx index bd9e5fd1bff..ce6dd315a43 100644 --- a/.storybook-s2/preview.tsx +++ b/.storybook-s2/preview.tsx @@ -35,7 +35,7 @@ channel.on(DARK_MODE_EVENT_NAME, (isDark: boolean) => { document.documentElement.dataset.colorScheme = isDark ? 'dark' : 'light'; }); -/** @type { import('@storybook/react').Preview } */ +/** @type {import('@storybook/react').Preview} */ const preview = { parameters: { controls: { diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 962c7e04584..cb1a8aa119d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -101,7 +101,7 @@ yarn test --coverage ``` ### Linting -The code is linted with [eslint](https://eslint.org/). The linter runs whenever you run the tests, but you can also run it with +The code is linted with [oxlint](https://oxc.rs/docs/guide/usage/linter.html). The linter runs whenever you run the tests, but you can also run it with ```bash yarn lint ``` diff --git a/eslint.config.mjs b/eslint.config.mjs deleted file mode 100644 index 0a4f190019e..00000000000 --- a/eslint.config.mjs +++ /dev/null @@ -1,505 +0,0 @@ -import react from 'eslint-plugin-react'; -import rulesdir from 'eslint-plugin-rulesdir'; -import jsxA11Y from 'eslint-plugin-jsx-a11y'; -import reactHooks from 'eslint-plugin-react-hooks'; -import jest from 'eslint-plugin-jest'; -import monorepo from '@jdb8/eslint-plugin-monorepo'; -import * as rspRules from 'eslint-plugin-rsp-rules'; -import globals from 'globals'; -import babelParser from '@babel/eslint-parser'; -import typescriptEslint from '@typescript-eslint/eslint-plugin'; -import jsdoc from 'eslint-plugin-jsdoc'; -import tseslint from 'typescript-eslint'; -import path from 'node:path'; -import {fileURLToPath} from 'node:url'; -import js from '@eslint/js'; -import {FlatCompat} from '@eslint/eslintrc'; - -import rulesDirPlugin from 'eslint-plugin-rulesdir'; -rulesDirPlugin.RULES_DIR = './bin'; - -const __filename = fileURLToPath(import.meta.url); -const __dirname = path.dirname(__filename); -const compat = new FlatCompat({ - baseDirectory: __dirname, - recommendedConfig: js.configs.recommended, - allConfig: js.configs.all -}); - -const OFF = 0; -const WARN = 1; -const ERROR = 2; - -export default [ - { - ignores: [ - 'packages/@react-aria/i18n/server', - 'packages/@spectrum-icons/color/**/*', - 'packages/@spectrum-icons/ui/**/*', - 'packages/@spectrum-icons/workflow/**/*', - 'packages/@spectrum-icons/illustrations/**/*', - 'packages/@spectrum-icons/express/**/*', - '**/node_modules', - 'packages/*/*/dist', - 'packages/*/*/i18n', - 'packages/react-aria/dist', - 'packages/react-aria/i18n', - 'packages/react-aria-components/dist', - 'packages/react-aria-components/i18n', - 'packages/react-stately/dist', - 'packages/dev/storybook-builder-parcel/preview.js', - 'packages/dev/optimize-locales-plugin/LocalesPlugin.d.ts', - 'examples/**/*', - 'starters/**/*', - 'scripts/icon-builder-fixture/**/*', - 'packages/@react-spectrum/s2/icon.d.ts', - 'packages/@react-spectrum/s2/spectrum-illustrations', - 'packages/dev/parcel-config-storybook/*', - 'packages/dev/parcel-resolver-storybook/*', - 'packages/dev/parcel-transformer-storybook/*', - 'packages/dev/storybook-builder-parcel/*', - 'packages/dev/storybook-react-parcel/*', - 'packages/dev/s2-docs/pages/**', - 'packages/dev/mcp/*/dist', - 'packages/dev/codemods/src/s1-to-s2/__testfixtures__/cli/**' - ] - }, - ...compat.extends('eslint:recommended'), - { - plugins: { - react, - rulesdir, - 'jsx-a11y': jsxA11Y, - 'react-hooks': reactHooks, - jest, - monorepo, - 'rsp-rules': rspRules - }, - - languageOptions: { - globals: { - ...globals.browser, - ...globals.node, - ...globals.mocha, - ...globals.jest, - importSpectrumCSS: 'readonly', - jest: true, - expect: true, - JSX: 'readonly', - NodeJS: 'readonly', - AsyncIterable: 'readonly', - FileSystemFileEntry: 'readonly', - FileSystemDirectoryEntry: 'readonly', - FileSystemEntry: 'readonly', - IS_REACT_ACT_ENVIRONMENT: 'readonly' - }, - - parser: babelParser, - ecmaVersion: 6, - sourceType: 'module', - - parserOptions: { - ecmaFeatures: { - legacyDecorators: true - } - } - }, - - settings: { - jsdoc: { - ignorePrivate: true, - publicFunctionsOnly: true - }, - - react: { - version: 'detect' - } - }, - - rules: { - 'no-fallthrough': OFF, - 'no-irregular-whitespace': [ERROR], - eqeqeq: [ERROR, 'smart'], - - 'no-console': OFF, - - 'no-unused-vars': [ - ERROR, - { - args: 'none', - vars: 'all', - varsIgnorePattern: '[rR]eact' - } - ], - 'no-unused-private-class-members': OFF, - - 'spaced-comment': [ - ERROR, - 'always', - { - exceptions: ['*', '#__PURE__'], - markers: ['/'] - } - ], - - 'max-depth': [WARN, 4], - radix: [ERROR, 'always'], - 'react/jsx-uses-react': WARN, - 'eol-last': ERROR, - 'arrow-spacing': ERROR, - 'space-before-blocks': [ERROR, 'always'], - 'space-infix-ops': ERROR, - 'no-new-wrappers': ERROR, - 'no-self-compare': ERROR, - 'no-nested-ternary': ERROR, - 'no-multiple-empty-lines': ERROR, - 'no-unneeded-ternary': ERROR, - // "no-duplicate-imports": ERROR, - 'react/display-name': OFF, - 'react/jsx-curly-spacing': [ERROR, 'never'], - 'react/jsx-indent-props': [ERROR, ERROR], - 'react/jsx-no-duplicate-props': ERROR, - 'react/jsx-no-literals': OFF, - 'react/jsx-no-undef': ERROR, - 'react/jsx-quotes': OFF, - 'react/jsx-sort-prop-types': OFF, - 'react/jsx-sort-props': OFF, - 'react/jsx-uses-vars': ERROR, - 'react/no-danger': OFF, - 'react/no-did-mount-set-state': OFF, - 'react/no-did-update-set-state': ERROR, - 'react/no-multi-comp': OFF, - 'react/no-set-state': OFF, - - 'react/no-unknown-property': [ - ERROR, - { - ignore: ['prefix'] - } - ], - - 'react/react-in-jsx-scope': ERROR, - 'react/require-extension': OFF, - - 'react/jsx-max-props-per-line': [ - ERROR, - { - when: 'multiline' - } - ], - - 'react/jsx-boolean-value': ERROR, - 'react/self-closing-comp': ERROR, - - // Core hooks rules - 'react-hooks/rules-of-hooks': ERROR, // https://github.com/facebook/react/blob/main/packages/eslint-plugin-react-hooks/CHANGELOG.md - 'react-hooks/exhaustive-deps': WARN, - - // React Compiler rules - 'react-hooks/config': ERROR, - 'react-hooks/error-boundaries': ERROR, - 'react-hooks/component-hook-factories': ERROR, - 'react-hooks/gating': ERROR, - 'react-hooks/globals': ERROR, - // 'react-hooks/immutability': ERROR, - // 'react-hooks/preserve-manual-memoization': ERROR, // No idea how to turn this one on yet - 'react-hooks/purity': ERROR, - // 'react-hooks/refs': ERROR, // can't turn on until https://github.com/facebook/react/issues/34775 is fixed - 'react-hooks/set-state-in-effect': ERROR, - 'react-hooks/set-state-in-render': ERROR, - 'react-hooks/static-components': ERROR, - 'react-hooks/unsupported-syntax': WARN, - 'react-hooks/use-memo': ERROR, - 'react-hooks/incompatible-library': WARN, - - 'rsp-rules/no-react-key': [ERROR], - 'rsp-rules/sort-imports': [ERROR], - 'rsp-rules/no-non-shadow-contains': [ERROR], - 'rsp-rules/safe-event-target': [ERROR], - 'rsp-rules/shadow-safe-active-element': [ERROR], - 'rsp-rules/faster-node-contains': [ERROR], - 'rulesdir/imports': [ERROR], - 'rulesdir/useLayoutEffectRule': [ERROR], - 'rulesdir/pure-render': [ERROR], - 'jsx-a11y/accessible-emoji': ERROR, - 'jsx-a11y/alt-text': ERROR, - 'jsx-a11y/anchor-has-content': ERROR, - 'jsx-a11y/anchor-is-valid': ERROR, - 'jsx-a11y/aria-activedescendant-has-tabindex': ERROR, - 'jsx-a11y/aria-props': ERROR, - 'jsx-a11y/aria-proptypes': ERROR, - 'jsx-a11y/aria-role': ERROR, - 'jsx-a11y/aria-unsupported-elements': ERROR, - 'jsx-a11y/click-events-have-key-events': ERROR, - 'jsx-a11y/heading-has-content': ERROR, - 'jsx-a11y/html-has-lang': ERROR, - 'jsx-a11y/iframe-has-title': ERROR, - 'jsx-a11y/img-redundant-alt': ERROR, - - 'jsx-a11y/interactive-supports-focus': [ - ERROR, - { - tabbable: ['button', 'checkbox', 'link', 'searchbox', 'spinbutton', 'switch', 'textbox'] - } - ], - - 'jsx-a11y/label-has-associated-control': [ - ERROR, - { - assert: 'either', - depth: 3 - } - ], - - 'jsx-a11y/media-has-caption': ERROR, - 'jsx-a11y/mouse-events-have-key-events': ERROR, - 'jsx-a11y/no-access-key': ERROR, - 'jsx-a11y/no-distracting-elements': ERROR, - 'jsx-a11y/no-interactive-element-to-noninteractive-role': ERROR, - - 'jsx-a11y/no-noninteractive-element-interactions': [ - WARN, - { - handlers: ['onClick', 'onMouseDown', 'onMouseUp', 'onKeyPress', 'onKeyDown', 'onKeyUp'] - } - ], - - 'jsx-a11y/no-noninteractive-element-to-interactive-role': [ - ERROR, - { - ul: ['listbox', 'menu', 'menubar', 'radiogroup', 'tablist', 'tree', 'treegrid'], - ol: ['listbox', 'menu', 'menubar', 'radiogroup', 'tablist', 'tree', 'treegrid'], - li: ['menuitem', 'option', 'row', 'tab', 'treeitem'], - table: ['grid'], - td: ['gridcell', 'columnheader', 'rowheader'], - th: ['columnheader', 'rowheader'] - } - ], - - 'jsx-a11y/no-noninteractive-tabindex': [ - ERROR, - { - tags: [], - roles: ['alertdialog', 'dialog', 'tabpanel'] - } - ], - - 'jsx-a11y/no-redundant-roles': ERROR, - - 'jsx-a11y/no-static-element-interactions': [ - ERROR, - { - handlers: ['onClick', 'onMouseDown', 'onMouseUp', 'onKeyPress', 'onKeyDown', 'onKeyUp'] - } - ], - - 'jsx-a11y/role-has-required-aria-props': ERROR, - 'jsx-a11y/role-supports-aria-props': ERROR, - 'jsx-a11y/scope': ERROR, - 'jsx-a11y/tabindex-no-positive': ERROR, - - 'monorepo/no-relative-import': ERROR - } - }, - { - files: ['packages/**/*.ts', 'packages/**/*.tsx'], - - plugins: { - react, - rulesdir, - 'jsx-a11y': jsxA11Y, - 'react-hooks': reactHooks, - jest, - '@typescript-eslint': typescriptEslint, - monorepo, - jsdoc - }, - - languageOptions: { - globals: { - globalThis: 'readonly' - }, - - parser: tseslint.parser, - ecmaVersion: 6, - sourceType: 'module', - - parserOptions: { - ecmaFeatures: { - jsx: true, - legacyDecorators: true - }, - - useJSXTextNode: true, - project: './tsconfig.json' - } - }, - - rules: { - 'jsdoc/require-description-complete-sentence': [ - ERROR, - { - abbreviations: ['e.g', 'i.e'] - } - ], - - 'jsdoc/check-alignment': ERROR, - 'jsdoc/check-indentation': ERROR, - - 'jsdoc/check-tag-names': [ - ERROR, - { - definedTags: ['selector', 'note'] - } - ], - - 'jsdoc/require-description': [ - ERROR, - { - exemptedBy: ['deprecated'], - checkConstructors: false - } - ], - - 'no-redeclare': OFF, - '@typescript-eslint/no-redeclare': ERROR, - 'no-unused-vars': OFF, - '@typescript-eslint/no-unused-vars': ERROR - } - }, - { - files: ['packages/**/src/**/*.ts', 'packages/**/src/**/*.tsx'], - ignores: ['packages/dev/**'], - rules: { - 'rsp-rules/no-package-root-imports': ERROR - } - }, - { - files: [ - '**/test/**', - '**/stories/**', - '**/docs/**', - '**/chromatic/**', - '**/chromatic-fc/**', - '**/__tests__/**' - ], - - rules: { - 'rsp-rules/no-react-key': [ERROR], - 'rsp-rules/act-events-test': ERROR, - 'rsp-rules/no-getByRole-toThrow': ERROR, - 'rsp-rules/no-non-shadow-contains': OFF, - 'rsp-rules/safe-event-target': OFF, - 'rsp-rules/shadow-safe-active-element': OFF, - 'rsp-rules/faster-node-contains': OFF, - 'rulesdir/imports': OFF, - 'monorepo/no-internal-import': OFF, - 'jsdoc/require-jsdoc': OFF - }, - - languageOptions: { - globals: { - ...globals.browser, - ...globals.node, - ...globals.mocha, - ...globals.jest, - importSpectrumCSS: 'readonly', - jest: true, - expect: true, - JSX: 'readonly', - NodeJS: 'readonly', - AsyncIterable: 'readonly', - FileSystemFileEntry: 'readonly', - FileSystemDirectoryEntry: 'readonly', - FileSystemEntry: 'readonly', - IS_REACT_ACT_ENVIRONMENT: 'readonly', - globalThis: 'readonly' - }, - - parser: tseslint.parser, - ecmaVersion: 6, - sourceType: 'module', - - parserOptions: { - // eventually move to projectService for faster linting - ecmaFeatures: { - legacyDecorators: true - } - } - } - }, - { - files: ['**/dev/**', '**/scripts/**'], - - rules: { - 'jsdoc/require-jsdoc': OFF, - 'jsdoc/require-description': OFF, - 'rsp-rules/safe-event-target': OFF - } - }, - { - files: ['packages/@react-aria/focus/src/**/*.ts', 'packages/@react-aria/focus/src/**/*.tsx'], - - rules: { - 'no-restricted-globals': [ - ERROR, - { - name: 'window', - message: 'Use getOwnerWindow from @react-aria/utils instead.' - }, - { - name: 'document', - message: 'Use getOwnerDocument from @react-aria/utils instead.' - } - ] - } - }, - { - files: [ - 'packages/react-aria/src/interactions/**/*.ts', - 'packages/react-aria/src/interactions/**/*.tsx' - ], - - rules: { - 'no-restricted-globals': [ - WARN, - { - name: 'window', - message: 'Use getOwnerWindow from @react-aria/utils instead.' - }, - { - name: 'document', - message: 'Use getOwnerDocument from @react-aria/utils instead.' - } - ] - } - }, - { - files: [ - 'packages/@react-aria/test-utils/src/**/*.ts', - 'packages/@react-aria/test-utils/src/**/*.tsx' - ], - - rules: { - 'rsp-rules/faster-node-contains': OFF, - 'rsp-rules/no-non-shadow-contains': OFF, - 'rsp-rules/shadow-safe-active-element': OFF - } - }, - { - files: ['packages/@react-spectrum/s2/**', 'packages/dev/s2-docs/**'], - - rules: { - 'react/react-in-jsx-scope': OFF - } - }, - { - files: ['packages/dev/style-macro-chrome-plugin/**'], - languageOptions: { - globals: { - ...globals.webextensions, - ...globals.browser - } - } - } -]; diff --git a/examples/rac-spectrum-tailwind/src/spectrum-preset.js b/examples/rac-spectrum-tailwind/src/spectrum-preset.js index 127202d74d2..5ab813145c0 100644 --- a/examples/rac-spectrum-tailwind/src/spectrum-preset.js +++ b/examples/rac-spectrum-tailwind/src/spectrum-preset.js @@ -378,7 +378,7 @@ module.exports = { error: 'var(--spectrum-alias-icon-color-error)' } }, - /** https://spectrum.adobe.com/page/states/#Keyboard-focus */ + /** https://spectrum.adobe.com/page/states/#Keyboard-focus. */ ringColor: { DEFAULT: 'var(--spectrum-alias-focus-ring-color)' }, @@ -390,12 +390,12 @@ module.exports = { /** For use when next to existing blue border. */ half: 'calc(var(--spectrum-alias-focus-ring-size) / 2)' }, - /** https://spectrum.adobe.com/page/object-styles/#Drop-shadow */ + /** https://spectrum.adobe.com/page/object-styles/#Drop-shadow. */ dropShadow: { DEFAULT: '0 var(--spectrum-alias-dropshadow-offset-y) var(--spectrum-alias-dropshadow-blur) var(--spectrum-alias-dropshadow-color)' }, - /** https://spectrum.adobe.com/page/object-styles/#Border-width */ + /** https://spectrum.adobe.com/page/object-styles/#Border-width. */ borderWidth: { DEFAULT: 'var(--spectrum-alias-border-size-thin)', none: '0', @@ -404,7 +404,7 @@ module.exports = { thicker: 'var(--spectrum-alias-border-size-thicker)', thickest: 'var(--spectrum-alias-border-size-thickest)' }, - /** https://spectrum.adobe.com/page/object-styles/#Rounding */ + /** https://spectrum.adobe.com/page/object-styles/#Rounding. */ borderRadius: { DEFAULT: 'var(--spectrum-alias-border-radius-regular)', xsmall: 'var(--spectrum-alias-border-radius-xsmall)', @@ -414,7 +414,7 @@ module.exports = { large: 'var(--spectrum-alias-border-radius-large)', full: '9999px' }, - /** https://spectrum.adobe.com/page/typography/#Font-sizes */ + /** https://spectrum.adobe.com/page/typography/#Font-sizes. */ fontSize: { DEFAULT: 'var(--spectrum-alias-font-size-default)', xs: 'var(--spectrum-global-dimension-font-size-50)', diff --git a/package.json b/package.json index 9b9aaad38ed..fef525dcb2e 100644 --- a/package.json +++ b/package.json @@ -56,7 +56,7 @@ "build": "make build", "test:ssr": "cross-env STRICT_MODE=1 yarn jest --runInBand --config jest.ssr.config.js", "ci-test": "cross-env STRICT_MODE=1 yarn jest --maxWorkers=2 && cross-env STRICT_MODE=1 yarn test:ssr --runInBand", - "lint": "concurrently \"yarn format:check\" \"yarn check-types\" \"eslint packages\" \"node scripts/lint-packages.js\" \"yarn constraints\"", + "lint": "concurrently \"yarn format:check\" \"yarn check-types\" \"oxlint packages\" \"node scripts/lint-packages.js\" \"yarn constraints\"", "jest": "jest", "copyrights": "babel-node --presets @babel/env ./scripts/addHeaders.js", "build:icons": "babel-node --presets @babel/env ./scripts/buildIcons.js", @@ -85,7 +85,6 @@ "@actions/github": "^1.1.0", "@babel/cli": "^7.24.1", "@babel/core": "^7.24.3", - "@babel/eslint-parser": "^7.27.1", "@babel/node": "^7.23.9", "@babel/plugin-proposal-decorators": "^7.24.1", "@babel/plugin-transform-runtime": "^7.24.3", @@ -93,9 +92,6 @@ "@babel/preset-react": "^7.24.1", "@babel/preset-typescript": "^7.24.1", "@babel/register": "^7.23.7", - "@eslint/compat": "^1.2.0", - "@eslint/eslintrc": "^3.1.0", - "@eslint/js": "^9.12.0", "@faker-js/faker": "^8.4.1", "@jdb8/eslint-plugin-monorepo": "^1.0.1", "@octokit/rest": "*", @@ -154,14 +150,8 @@ "cross-spawn": "^7.0.5", "delta-e": "^0.0.8", "diff": "^5.1.0", - "eslint": "^9.12.0", - "eslint-plugin-import": "^2.31.0", - "eslint-plugin-jest": "^28.8.3", - "eslint-plugin-jsdoc": "^50.4.1", - "eslint-plugin-jsx-a11y": "^6.10.0", - "eslint-plugin-react": "^7.37.1", + "eslint-import-resolver-node": "^0.3.10", "eslint-plugin-react-hooks": "^7.0.0", - "eslint-plugin-rulesdir": "^0.2.2", "exceljs": "^4.4.0", "fast-check": "^2.19.0", "fast-glob": "^3.1.0", @@ -182,6 +172,7 @@ "motion": "^12.23.6", "npm-cli-login": "^1.0.0", "oxfmt": "^0.48.0", + "oxlint": "^1.63.0", "parcel": "^2.16.3", "parcel-optimizer-strict-mode": "workspace:^", "patch-package": "^6.2.0", @@ -208,7 +199,6 @@ "tailwindcss-animate": "^1.0.7", "tempy": "^0.5.0", "typescript": "^5.8.2", - "typescript-eslint": "^8.38.0", "unplugin-parcel-macros": "^0.1.1", "verdaccio": "^6.0.0", "vite": "^7.3.2", diff --git a/packages/@adobe/react-spectrum/docs/labeledvalue/types.ts b/packages/@adobe/react-spectrum/docs/labeledvalue/types.ts index fd262b87c92..5d81dd98643 100644 --- a/packages/@adobe/react-spectrum/docs/labeledvalue/types.ts +++ b/packages/@adobe/react-spectrum/docs/labeledvalue/types.ts @@ -14,6 +14,9 @@ export interface LabeledValueProps extends LabeledValueBaseProps { | DateTime | RangeValue | ReactElement; - /** Formatting options for the value. The available options depend on the type passed to the `value` prop. */ + /** + * Formatting options for the value. The available options depend on the type passed to the + * `value` prop. + */ formatOptions?: Intl.NumberFormatOptions | Intl.DateTimeFormatOptions | Intl.ListFormatOptions; } diff --git a/packages/@adobe/react-spectrum/src/accordion/Accordion.tsx b/packages/@adobe/react-spectrum/src/accordion/Accordion.tsx index c40578652f3..ebe670ab548 100644 --- a/packages/@adobe/react-spectrum/src/accordion/Accordion.tsx +++ b/packages/@adobe/react-spectrum/src/accordion/Accordion.tsx @@ -74,7 +74,10 @@ export interface SpectrumDisclosureProps StyleProps { /** Whether the Disclosure should be displayed with a quiet style. */ isQuiet?: boolean; - /** The contents of the disclosure. The first child should be the header, and the second child should be the panel. */ + /** + * The contents of the disclosure. The first child should be the header, and the second child + * should be the panel. + */ children: React.ReactNode; } @@ -140,6 +143,7 @@ export const DisclosurePanel = /*#__PURE__*/ (forwardRef as forwardRefType)( export interface SpectrumDisclosureTitleProps extends DOMProps, AriaLabelingProps, StyleProps { /** * The heading level of the disclosure header. + * * @default 3 */ level?: number; diff --git a/packages/@adobe/react-spectrum/src/actionbar/ActionBar.tsx b/packages/@adobe/react-spectrum/src/actionbar/ActionBar.tsx index 02e4f1cf33b..c486c5d515b 100644 --- a/packages/@adobe/react-spectrum/src/actionbar/ActionBar.tsx +++ b/packages/@adobe/react-spectrum/src/actionbar/ActionBar.tsx @@ -32,13 +32,19 @@ import {useProviderProps} from '../provider/Provider'; import {useStyleProps} from '../utils/styleProps'; interface ActionBarProps { - /** An list of `Item` elements or a function. If the latter, a list of items must be provided using the `items` prop. */ + /** + * An list of `Item` elements or a function. If the latter, a list of items must be provided using + * the `items` prop. + */ children: ItemElement | ItemElement[] | ItemRenderer; /** A list of items to display as children. Must be used with a function as the sole child. */ items?: Iterable; /** A list of keys to disable. */ disabledKeys?: Iterable; - /** The number of selected items that the ActionBar is currently linked to. If 0, the ActionBar is hidden. */ + /** + * The number of selected items that the ActionBar is currently linked to. If 0, the ActionBar is + * hidden. + */ selectedItemCount: number | 'all'; /** Handler that is called when the ActionBar clear button is pressed. */ onClearSelection: () => void; @@ -48,9 +54,10 @@ interface ActionBarProps { onAction?: (key: Key) => void; /** * Defines when the text within the buttons should be hidden and only the icon should be shown. - * When set to 'hide', the text is always shown in a tooltip. When set to 'collapse', the text is visible - * if space is available, and hidden when space is limited. The text is always visible when the item - * is collapsed into a menu. + * When set to 'hide', the text is always shown in a tooltip. When set to 'collapse', the text is + * visible if space is available, and hidden when space is limited. The text is always visible + * when the item is collapsed into a menu. + * * @default 'collapse' */ buttonLabelBehavior?: 'show' | 'collapse' | 'hide'; @@ -59,7 +66,8 @@ interface ActionBarProps { export interface SpectrumActionBarProps extends ActionBarProps, DOMProps, StyleProps {} /** - * Action bars are used for single and bulk selection patterns when a user needs to perform actions on one or more items at the same time. + * Action bars are used for single and bulk selection patterns when a user needs to perform actions + * on one or more items at the same time. */ export const ActionBar = React.forwardRef(function ActionBar( props: SpectrumActionBarProps, diff --git a/packages/@adobe/react-spectrum/src/actionbar/ActionBarContainer.tsx b/packages/@adobe/react-spectrum/src/actionbar/ActionBarContainer.tsx index 1f71a8486f1..863a5b59ef5 100644 --- a/packages/@adobe/react-spectrum/src/actionbar/ActionBarContainer.tsx +++ b/packages/@adobe/react-spectrum/src/actionbar/ActionBarContainer.tsx @@ -21,7 +21,10 @@ import {useProviderProps} from '../provider/Provider'; import {useStyleProps} from '../utils/styleProps'; interface ActionBarContainerProps { - /** The contents of the ActionBarContainer. Should include a ActionBar and the renderable content it is associated with. */ + /** + * The contents of the ActionBarContainer. Should include a ActionBar and the renderable content + * it is associated with. + */ children: ReactNode; } diff --git a/packages/@adobe/react-spectrum/src/actiongroup/ActionGroup.tsx b/packages/@adobe/react-spectrum/src/actiongroup/ActionGroup.tsx index 2e9c8ef52a8..eabceba43ac 100644 --- a/packages/@adobe/react-spectrum/src/actiongroup/ActionGroup.tsx +++ b/packages/@adobe/react-spectrum/src/actiongroup/ActionGroup.tsx @@ -54,16 +54,23 @@ import {useStyleProps} from '../utils/styleProps'; import {useValueEffect} from 'react-aria/private/utils/useValueEffect'; export interface SpectrumActionGroupProps extends AriaActionGroupProps, StyleProps { - /** Whether the ActionButtons should be displayed with a [emphasized style](https://spectrum.adobe.com/page/action-button/#Emphasis). */ + /** + * Whether the ActionButtons should be displayed with a [emphasized + * style](https://spectrum.adobe.com/page/action-button/#Emphasis). + */ isEmphasized?: boolean; /** * Sets the amount of space between buttons. + * * @default 'regular' */ density?: 'compact' | 'regular'; /** Whether the ActionButtons should be justified in their container. */ isJustified?: boolean; - /** Whether ActionButtons should use the [quiet style](https://spectrum.adobe.com/page/action-button/#Quiet). */ + /** + * Whether ActionButtons should use the [quiet + * style](https://spectrum.adobe.com/page/action-button/#Quiet). + */ isQuiet?: boolean; /** The static color style to apply. Useful when the ActionGroup appears over a color background. */ staticColor?: 'white' | 'black'; @@ -71,14 +78,16 @@ export interface SpectrumActionGroupProps extends AriaActionGroupProps, St * Defines the behavior of the ActionGroup when the buttons do not fit in the available space. * When set to 'wrap', the items wrap to form a new line. When set to 'collapse', the items that * do not fit are collapsed into a dropdown menu. + * * @default 'wrap' */ overflowMode?: 'wrap' | 'collapse'; /** * Defines when the text within the buttons should be hidden and only the icon should be shown. - * When set to 'hide', the text is always shown in a tooltip. When set to 'collapse', the text is visible - * if space is available, and hidden when space is limited. The text is always visible when the item - * is collapsed into a menu. + * When set to 'hide', the text is always shown in a tooltip. When set to 'collapse', the text is + * visible if space is available, and hidden when space is limited. The text is always visible + * when the item is collapsed into a menu. + * * @default 'show' */ buttonLabelBehavior?: 'show' | 'collapse' | 'hide'; diff --git a/packages/@adobe/react-spectrum/src/autocomplete/SearchAutocomplete.tsx b/packages/@adobe/react-spectrum/src/autocomplete/SearchAutocomplete.tsx index 12691bbee29..b098b193830 100644 --- a/packages/@adobe/react-spectrum/src/autocomplete/SearchAutocomplete.tsx +++ b/packages/@adobe/react-spectrum/src/autocomplete/SearchAutocomplete.tsx @@ -77,29 +77,41 @@ export interface SpectrumSearchAutocompleteProps StyleProps, Omit { /** - * The interaction required to display the SearchAutocomplete menu. Note that this prop has no effect on the mobile SearchAutocomplete experience. + * The interaction required to display the SearchAutocomplete menu. Note that this prop has no + * effect on the mobile SearchAutocomplete experience. + * * @default 'input' */ menuTrigger?: MenuTriggerAction; /** Whether the SearchAutocomplete should be displayed with a quiet style. */ isQuiet?: boolean; - /** Alignment of the menu relative to the input target. + /** + * Alignment of the menu relative to the input target. + * * @default 'start' */ align?: 'start' | 'end'; /** * Direction the menu will render relative to the SearchAutocomplete. + * * @default 'bottom' */ direction?: 'bottom' | 'top'; - /** The current loading state of the SearchAutocomplete. Determines whether or not the progress circle should be shown. */ + /** + * The current loading state of the SearchAutocomplete. Determines whether or not the progress + * circle should be shown. + */ loadingState?: LoadingState; /** * Whether the menu should automatically flip direction when space is limited. + * * @default true */ shouldFlip?: boolean; - /** Width of the menu. By default, matches width of the trigger. Note that the minimum width of the dropdown is always equal to the trigger's width. */ + /** + * Width of the menu. By default, matches width of the trigger. Note that the minimum width of the + * dropdown is always equal to the trigger's width. + */ menuWidth?: DimensionValue; onLoadMore?: () => void; /** An icon to display at the start of the input. */ diff --git a/packages/@adobe/react-spectrum/src/badge/Badge.tsx b/packages/@adobe/react-spectrum/src/badge/Badge.tsx index 67ba761af2f..0ba42bd507e 100644 --- a/packages/@adobe/react-spectrum/src/badge/Badge.tsx +++ b/packages/@adobe/react-spectrum/src/badge/Badge.tsx @@ -42,7 +42,8 @@ export interface SpectrumBadgeProps extends DOMProps, StyleProps, AriaLabelingPr } /** - * Badges are used for showing a small amount of color-categorized metadata, ideal for getting a user's attention. + * Badges are used for showing a small amount of color-categorized metadata, ideal for getting a + * user's attention. */ export const Badge = forwardRef(function Badge( props: SpectrumBadgeProps, diff --git a/packages/@adobe/react-spectrum/src/breadcrumbs/Breadcrumbs.tsx b/packages/@adobe/react-spectrum/src/breadcrumbs/Breadcrumbs.tsx index 4008e9c6e31..801e1d195ce 100644 --- a/packages/@adobe/react-spectrum/src/breadcrumbs/Breadcrumbs.tsx +++ b/packages/@adobe/react-spectrum/src/breadcrumbs/Breadcrumbs.tsx @@ -36,6 +36,7 @@ export interface SpectrumBreadcrumbsProps extends AriaBreadcrumbsProps, Style onAction?: (key: Key) => void; /** * Size of the Breadcrumbs including spacing and layout. + * * @default 'L' */ size?: 'S' | 'M' | 'L'; diff --git a/packages/@adobe/react-spectrum/src/button/ActionButton.tsx b/packages/@adobe/react-spectrum/src/button/ActionButton.tsx index a9fbe11ed23..b22bd54fb76 100644 --- a/packages/@adobe/react-spectrum/src/button/ActionButton.tsx +++ b/packages/@adobe/react-spectrum/src/button/ActionButton.tsx @@ -28,15 +28,19 @@ import {useStyleProps} from '../utils/styleProps'; export interface SpectrumActionButtonProps extends AriaBaseButtonProps, Omit, StyleProps { - /** Whether the button should be displayed with a [quiet style](https://spectrum.adobe.com/page/action-button/#Quiet). */ + /** + * Whether the button should be displayed with a [quiet + * style](https://spectrum.adobe.com/page/action-button/#Quiet). + */ isQuiet?: boolean; /** The static color style to apply. Useful when the button appears over a color background. */ staticColor?: 'white' | 'black'; } /** - * ActionButtons allow users to perform an action. - * They’re used for similar, task-based options within a workflow, and are ideal for interfaces where buttons aren’t meant to draw a lot of attention. + * ActionButtons allow users to perform an action. They’re used for similar, task-based options + * within a workflow, and are ideal for interfaces where buttons aren’t meant to draw a lot of + * attention. */ export const ActionButton = React.forwardRef(function ActionButton( props: SpectrumActionButtonProps, diff --git a/packages/@adobe/react-spectrum/src/button/Button.tsx b/packages/@adobe/react-spectrum/src/button/Button.tsx index 703902878ef..a88dacd04fb 100644 --- a/packages/@adobe/react-spectrum/src/button/Button.tsx +++ b/packages/@adobe/react-spectrum/src/button/Button.tsx @@ -49,6 +49,7 @@ export interface SpectrumButtonProps isPending?: boolean; /** * Whether the button should be displayed with a quiet style. + * * @deprecated */ isQuiet?: boolean; diff --git a/packages/@adobe/react-spectrum/src/button/ToggleButton.tsx b/packages/@adobe/react-spectrum/src/button/ToggleButton.tsx index 720a5697cee..0deb0095545 100644 --- a/packages/@adobe/react-spectrum/src/button/ToggleButton.tsx +++ b/packages/@adobe/react-spectrum/src/button/ToggleButton.tsx @@ -43,7 +43,10 @@ export interface SpectrumToggleButtonProps | 'name' | 'value' > { - /** Whether the button should be displayed with an [emphasized style](https://spectrum.adobe.com/page/action-button/#Emphasis). */ + /** + * Whether the button should be displayed with an [emphasized + * style](https://spectrum.adobe.com/page/action-button/#Emphasis). + */ isEmphasized?: boolean; } diff --git a/packages/@adobe/react-spectrum/src/buttongroup/ButtonGroup.tsx b/packages/@adobe/react-spectrum/src/buttongroup/ButtonGroup.tsx index cbd35ac5c25..dea4e73a105 100644 --- a/packages/@adobe/react-spectrum/src/buttongroup/ButtonGroup.tsx +++ b/packages/@adobe/react-spectrum/src/buttongroup/ButtonGroup.tsx @@ -29,6 +29,7 @@ export interface SpectrumButtonGroupProps extends DOMProps, StyleProps { /** * The axis the ButtonGroup should align with. Setting this to 'vertical' will prevent * any switching behaviors between 'vertical' and 'horizontal'. + * * @default 'horizontal' */ orientation?: Orientation; @@ -36,6 +37,7 @@ export interface SpectrumButtonGroupProps extends DOMProps, StyleProps { children: ReactNode; /** * The alignment of the buttons within the ButtonGroup. + * * @default 'start' */ align?: Alignment | 'center'; diff --git a/packages/@adobe/react-spectrum/src/calendar/Calendar.tsx b/packages/@adobe/react-spectrum/src/calendar/Calendar.tsx index 0546354b15d..10121af74e4 100644 --- a/packages/@adobe/react-spectrum/src/calendar/Calendar.tsx +++ b/packages/@adobe/react-spectrum/src/calendar/Calendar.tsx @@ -26,14 +26,16 @@ export interface SpectrumCalendarProps extends AriaCalendarProps, StyleProps { /** * The number of months to display at once. Up to 3 months are supported. + * * @default 1 */ visibleMonths?: number; /** - * A function to create a new [Calendar](https://react-spectrum.adobe.com/internationalized/date/Calendar.html) - * object for a given calendar identifier. If not provided, the `createCalendar` function - * from `@internationalized/date` will be used. + * A function to create a new + * [Calendar](https://react-spectrum.adobe.com/internationalized/date/Calendar.html) object for a + * given calendar identifier. If not provided, the `createCalendar` function from + * `@internationalized/date` will be used. */ createCalendar?: (identifier: CalendarIdentifier) => ICalendar; } diff --git a/packages/@adobe/react-spectrum/src/calendar/RangeCalendar.tsx b/packages/@adobe/react-spectrum/src/calendar/RangeCalendar.tsx index 3768a817b2e..83a7a567726 100644 --- a/packages/@adobe/react-spectrum/src/calendar/RangeCalendar.tsx +++ b/packages/@adobe/react-spectrum/src/calendar/RangeCalendar.tsx @@ -26,20 +26,23 @@ export interface SpectrumRangeCalendarProps extends AriaRangeCalendarProps, StyleProps { /** * The number of months to display at once. Up to 3 months are supported. + * * @default 1 */ visibleMonths?: number; /** - * A function to create a new [Calendar](https://react-spectrum.adobe.com/internationalized/date/Calendar.html) - * object for a given calendar identifier. If not provided, the `createCalendar` function - * from `@internationalized/date` will be used. + * A function to create a new + * [Calendar](https://react-spectrum.adobe.com/internationalized/date/Calendar.html) object for a + * given calendar identifier. If not provided, the `createCalendar` function from + * `@internationalized/date` will be used. */ createCalendar?: (identifier: CalendarIdentifier) => ICalendar; } /** - * RangeCalendars display a grid of days in one or more months and allow users to select a contiguous range of dates. + * RangeCalendars display a grid of days in one or more months and allow users to select a + * contiguous range of dates. */ export const RangeCalendar = React.forwardRef(function RangeCalendar( props: SpectrumRangeCalendarProps, diff --git a/packages/@adobe/react-spectrum/src/card/BaseLayout.tsx b/packages/@adobe/react-spectrum/src/card/BaseLayout.tsx index 912d3c126a3..0b9a213e77a 100644 --- a/packages/@adobe/react-spectrum/src/card/BaseLayout.tsx +++ b/packages/@adobe/react-spectrum/src/card/BaseLayout.tsx @@ -29,6 +29,7 @@ export interface BaseLayoutOptions { scale?: Scale; /** * The margin around the grid view between the edges and the items. + * * @default 24 */ margin?: number; diff --git a/packages/@adobe/react-spectrum/src/card/GalleryLayout.tsx b/packages/@adobe/react-spectrum/src/card/GalleryLayout.tsx index 9af9966a1b8..463ce49ebcb 100644 --- a/packages/@adobe/react-spectrum/src/card/GalleryLayout.tsx +++ b/packages/@adobe/react-spectrum/src/card/GalleryLayout.tsx @@ -21,27 +21,32 @@ export interface GalleryLayoutOptions extends BaseLayoutOptions { // cardSize?: 'S' | 'M' | 'L', /** * The the default row height. Note this must be larger than the min item height. + * * @default 208 */ idealRowHeight?: number; /** * The spacing between items. + * * @default 18 x 18 */ itemSpacing?: Size; /** * The vertical padding for an item. + * * @default 78 */ itemPadding?: number; /** * Minimum size for a item in the grid. + * * @default 136 x 136 */ minItemSize?: Size; /** - * Target for adding extra weight to elements during linear partitioning. Anything with an aspect ratio smaler than this value - * will be targeted. + * Target for adding extra weight to elements during linear partitioning. Anything with an aspect + * ratio smaler than this value will be targeted. + * * @type {number} */ threshold?: number; @@ -95,10 +100,10 @@ export class GalleryLayout extends BaseLayout { } /** - * Takes a row of widths and if there are any widths smaller than the min-width, leech width starting from - * the widest in the row until it can't give anymore, then move to the second widest and so forth. - * Do this until all assets meet the min-width. - * */ + * Takes a row of widths and if there are any widths smaller than the min-width, leech width + * starting from the widest in the row until it can't give anymore, then move to the second widest + * and so forth. Do this until all assets meet the min-width. + */ _distributeWidths(widths: number[]): boolean { // create a copy of the widths array and sort it largest to smallest let sortedWidths = widths.concat().sort((a, b) => (a[1] > b[1] ? -1 : 1)); diff --git a/packages/@adobe/react-spectrum/src/card/GridLayout.tsx b/packages/@adobe/react-spectrum/src/card/GridLayout.tsx index 4820e986bb1..70c95785269 100644 --- a/packages/@adobe/react-spectrum/src/card/GridLayout.tsx +++ b/packages/@adobe/react-spectrum/src/card/GridLayout.tsx @@ -23,31 +23,38 @@ export interface GridLayoutOptions extends BaseLayoutOptions { // cardSize?: 'S' | 'M' | 'L', /** * The minimum item size. + * * @default 208 x 208 for horizontal card orientation. 102 x 102 for vertical card orientation. */ minItemSize?: Size; /** * The maximum item size. + * * @default Infinity */ maxItemSize?: Size; /** * The minimum space required between items. + * * @default 18 x 18 */ minSpace?: Size; /** * The maximum number of columns. + * * @default Infinity */ maxColumns?: number; /** - * The additional padding along the card's main axis. Affects the sizing of the content area following the card image. + * The additional padding along the card's main axis. Affects the sizing of the content area + * following the card image. + * * @default 95 */ itemPadding?: number; /** * The orientation of the cards withn the grid. + * * @default vertical */ cardOrientation?: Orientation; diff --git a/packages/@adobe/react-spectrum/src/card/WaterfallLayout.tsx b/packages/@adobe/react-spectrum/src/card/WaterfallLayout.tsx index 17e5d6f51d0..f608251dc38 100644 --- a/packages/@adobe/react-spectrum/src/card/WaterfallLayout.tsx +++ b/packages/@adobe/react-spectrum/src/card/WaterfallLayout.tsx @@ -19,21 +19,25 @@ import {Key, KeyboardDelegate} from '@react-types/shared'; export interface WaterfallLayoutOptions extends BaseLayoutOptions { /** * The minimum item size. + * * @default 240 x 136 */ minItemSize?: Size; /** * The maximum item size. + * * @default Infinity */ maxItemSize?: Size; /** * The minimum space required between items. + * * @default 18 x 18 */ minSpace?: Size; /** * The maximum number of columns. + * * @default Infinity */ maxColumns?: number; diff --git a/packages/@adobe/react-spectrum/src/checkbox/Checkbox.tsx b/packages/@adobe/react-spectrum/src/checkbox/Checkbox.tsx index 45a4596c8a4..a70606c6ede 100644 --- a/packages/@adobe/react-spectrum/src/checkbox/Checkbox.tsx +++ b/packages/@adobe/react-spectrum/src/checkbox/Checkbox.tsx @@ -36,8 +36,10 @@ export interface SpectrumCheckboxProps extends Omit | ReactElement[]; /** * The axis the checkboxes should align with. + * * @default 'vertical' */ orientation?: Orientation; diff --git a/packages/@adobe/react-spectrum/src/color/ColorArea.tsx b/packages/@adobe/react-spectrum/src/color/ColorArea.tsx index b5be5803dc1..e48d72cf8dc 100644 --- a/packages/@adobe/react-spectrum/src/color/ColorArea.tsx +++ b/packages/@adobe/react-spectrum/src/color/ColorArea.tsx @@ -33,7 +33,8 @@ export interface SpectrumColorAreaProps } /** - * ColorArea allows users to adjust two channels of an RGB, HSL or HSB color value against a two-dimensional gradient background. + * ColorArea allows users to adjust two channels of an RGB, HSL or HSB color value against a + * two-dimensional gradient background. */ export const ColorArea = React.forwardRef(function ColorArea( props: SpectrumColorAreaProps, diff --git a/packages/@adobe/react-spectrum/src/color/ColorPicker.tsx b/packages/@adobe/react-spectrum/src/color/ColorPicker.tsx index abf1e935c4f..515c24da863 100644 --- a/packages/@adobe/react-spectrum/src/color/ColorPicker.tsx +++ b/packages/@adobe/react-spectrum/src/color/ColorPicker.tsx @@ -32,12 +32,14 @@ export interface SpectrumColorPickerProps children?: ReactNode; /** * The size of the color swatch. - * @default "M" + * + * @default 'M' */ size?: 'XS' | 'S' | 'M' | 'L'; /** * The corner rounding of the color swatch. - * @default "default" + * + * @default 'default' */ rounding?: 'default' | 'none' | 'full'; } diff --git a/packages/@adobe/react-spectrum/src/color/ColorSlider.tsx b/packages/@adobe/react-spectrum/src/color/ColorSlider.tsx index 32bc196ebfa..0db6b00544f 100644 --- a/packages/@adobe/react-spectrum/src/color/ColorSlider.tsx +++ b/packages/@adobe/react-spectrum/src/color/ColorSlider.tsx @@ -30,7 +30,10 @@ import {useProviderProps} from '../provider/Provider'; import {useStyleProps} from '../utils/styleProps'; export interface SpectrumColorSliderProps extends AriaColorSliderProps, StyleProps { - /** Whether the value label is displayed. True by default if there is a label, false by default if not. */ + /** + * Whether the value label is displayed. True by default if there is a label, false by default if + * not. + */ showValueLabel?: boolean; /** A ContextualHelp element to place next to the label. */ contextualHelp?: ReactNode; diff --git a/packages/@adobe/react-spectrum/src/color/ColorSwatch.tsx b/packages/@adobe/react-spectrum/src/color/ColorSwatch.tsx index cbf29e6fe14..1bc88eb7b35 100644 --- a/packages/@adobe/react-spectrum/src/color/ColorSwatch.tsx +++ b/packages/@adobe/react-spectrum/src/color/ColorSwatch.tsx @@ -24,12 +24,14 @@ import {useStyleProps} from '../utils/styleProps'; export interface SpectrumColorSwatchProps extends AriaColorSwatchProps, StyleProps { /** * The size of the ColorSwatch. - * @default "M" + * + * @default 'M' */ size?: 'XS' | 'S' | 'M' | 'L'; /** * The corner rounding of the ColorSwatch. - * @default "default" + * + * @default 'default' */ rounding?: 'default' | 'none' | 'full'; } diff --git a/packages/@adobe/react-spectrum/src/color/ColorSwatchPicker.tsx b/packages/@adobe/react-spectrum/src/color/ColorSwatchPicker.tsx index 66650d147a8..c551e50634b 100644 --- a/packages/@adobe/react-spectrum/src/color/ColorSwatchPicker.tsx +++ b/packages/@adobe/react-spectrum/src/color/ColorSwatchPicker.tsx @@ -29,17 +29,20 @@ export interface SpectrumColorSwatchPickerProps children: ReactNode; /** * The amount of padding between the swatches. - * @default "regular" + * + * @default 'regular' */ density?: 'compact' | 'regular' | 'spacious'; /** * The size of the color swatches. - * @default "M" + * + * @default 'M' */ size?: 'XS' | 'S' | 'M' | 'L'; /** * The corner rounding of the color swatches. - * @default "none" + * + * @default 'none' */ rounding?: 'none' | 'default' | 'full'; } diff --git a/packages/@adobe/react-spectrum/src/combobox/ComboBox.tsx b/packages/@adobe/react-spectrum/src/combobox/ComboBox.tsx index 6465ce7aec5..eb984dc92fe 100644 --- a/packages/@adobe/react-spectrum/src/combobox/ComboBox.tsx +++ b/packages/@adobe/react-spectrum/src/combobox/ComboBox.tsx @@ -90,40 +90,54 @@ export interface SpectrumComboBoxProps StyleProps, Omit { /** - * The interaction required to display the ComboBox menu. Note that this prop has no effect on the mobile ComboBox experience. + * The interaction required to display the ComboBox menu. Note that this prop has no effect on the + * mobile ComboBox experience. + * * @default 'input' */ menuTrigger?: MenuTriggerAction; /** Whether the ComboBox should be displayed with a quiet style. */ isQuiet?: boolean; - /** Alignment of the menu relative to the input target. + /** + * Alignment of the menu relative to the input target. + * * @default 'start' */ align?: 'start' | 'end'; /** * Direction the menu will render relative to the ComboBox. + * * @default 'bottom' */ direction?: 'bottom' | 'top'; - /** The current loading state of the ComboBox. Determines whether or not the progress circle should be shown. */ + /** + * The current loading state of the ComboBox. Determines whether or not the progress circle should + * be shown. + */ loadingState?: LoadingState; /** * Whether the menu should automatically flip direction when space is limited. + * * @default true */ shouldFlip?: boolean; - /** Width of the menu. By default, matches width of the combobox. Note that the minimum width of the dropdown is always equal to the combobox's width. */ + /** + * Width of the menu. By default, matches width of the combobox. Note that the minimum width of + * the dropdown is always equal to the combobox's width. + */ menuWidth?: DimensionValue; /** - * Whether the text or key of the selected item is submitted as part of an HTML form. - * When `allowsCustomValue` is `true`, this option does not apply and the text is always submitted. + * Whether the text or key of the selected item is submitted as part of an HTML form. When + * `allowsCustomValue` is `true`, this option does not apply and the text is always submitted. + * * @default 'text' */ formValue?: 'text' | 'key'; } /** - * ComboBoxes combine a text entry with a picker menu, allowing users to filter longer lists to only the selections matching a query. + * ComboBoxes combine a text entry with a picker menu, allowing users to filter longer lists to only + * the selections matching a query. */ export const ComboBox = React.forwardRef(function ComboBox( props: SpectrumComboBoxProps, diff --git a/packages/@adobe/react-spectrum/src/contextualhelp/ContextualHelp.tsx b/packages/@adobe/react-spectrum/src/contextualhelp/ContextualHelp.tsx index 15a061398bb..3dc5e9cdae5 100644 --- a/packages/@adobe/react-spectrum/src/contextualhelp/ContextualHelp.tsx +++ b/packages/@adobe/react-spectrum/src/contextualhelp/ContextualHelp.tsx @@ -35,18 +35,21 @@ export interface SpectrumContextualHelpProps children: ReactNode; /** * Indicates whether contents are informative or provides helpful guidance. + * * @default 'help' */ variant?: 'help' | 'info'; /** * The placement of the popover with respect to the action button. + * * @default 'bottom start' */ placement?: Placement; } /** - * Contextual help shows a user extra information about the state of an adjacent component, or a total view. + * Contextual help shows a user extra information about the state of an adjacent component, or a + * total view. */ export const ContextualHelp = React.forwardRef(function ContextualHelp( props: SpectrumContextualHelpProps, diff --git a/packages/@adobe/react-spectrum/src/datepicker/DateField.tsx b/packages/@adobe/react-spectrum/src/datepicker/DateField.tsx index b537e76a963..4be86f9e2ad 100644 --- a/packages/@adobe/react-spectrum/src/datepicker/DateField.tsx +++ b/packages/@adobe/react-spectrum/src/datepicker/DateField.tsx @@ -45,11 +45,13 @@ export interface SpectrumDateFieldBase StyleProps { /** * Whether the date picker should be displayed with a quiet style. + * * @default false */ isQuiet?: boolean; /** * Whether to show the localized date format as help text below the field. + * * @default false */ showFormatHelpText?: boolean; diff --git a/packages/@adobe/react-spectrum/src/datepicker/DatePicker.tsx b/packages/@adobe/react-spectrum/src/datepicker/DatePicker.tsx index 00f447cbd3e..6b3a2c61b7d 100644 --- a/packages/@adobe/react-spectrum/src/datepicker/DatePicker.tsx +++ b/packages/@adobe/react-spectrum/src/datepicker/DatePicker.tsx @@ -50,18 +50,22 @@ import {useProviderProps} from '../provider/Provider'; export interface SpectrumDatePickerBase extends SpectrumDateFieldBase, SpectrumLabelableProps, StyleProps { /** - * The maximum number of months to display at once in the calendar popover, if screen space permits. + * The maximum number of months to display at once in the calendar popover, if screen space + * permits. + * * @default 1 */ maxVisibleMonths?: number; /** * Whether the calendar popover should automatically flip direction when space is limited. + * * @default true */ shouldFlip?: boolean; /** - * A function to create a new [Calendar](https://react-spectrum.adobe.com/internationalized/date/Calendar.html) - * object for a given calendar identifier. This will be used for the popover calendar. If not provided, the + * A function to create a new + * [Calendar](https://react-spectrum.adobe.com/internationalized/date/Calendar.html) object for a + * given calendar identifier. This will be used for the popover calendar. If not provided, the * `createCalendar` function from `@internationalized/date` will be used. */ createCalendar?: (identifier: CalendarIdentifier) => ICalendar; @@ -73,7 +77,8 @@ export interface SpectrumDatePickerProps SpectrumDatePickerBase {} /** - * DatePickers combine a DateField and a Calendar popover to allow users to enter or select a date and time value. + * DatePickers combine a DateField and a Calendar popover to allow users to enter or select a date + * and time value. */ export const DatePicker = React.forwardRef(function DatePicker( props: SpectrumDatePickerProps, diff --git a/packages/@adobe/react-spectrum/src/datepicker/TimeField.tsx b/packages/@adobe/react-spectrum/src/datepicker/TimeField.tsx index 1203a57b89e..2145384be52 100644 --- a/packages/@adobe/react-spectrum/src/datepicker/TimeField.tsx +++ b/packages/@adobe/react-spectrum/src/datepicker/TimeField.tsx @@ -44,6 +44,7 @@ export interface SpectrumTimeFieldProps InputDOMProps { /** * Whether the time field should be displayed with a quiet style. + * * @default false */ isQuiet?: boolean; diff --git a/packages/@adobe/react-spectrum/src/dialog/AlertDialog.tsx b/packages/@adobe/react-spectrum/src/dialog/AlertDialog.tsx index 9583141f1e9..e93f0ae8325 100644 --- a/packages/@adobe/react-spectrum/src/dialog/AlertDialog.tsx +++ b/packages/@adobe/react-spectrum/src/dialog/AlertDialog.tsx @@ -30,7 +30,7 @@ import {useLocalizedStringFormatter} from 'react-aria/useLocalizedStringFormatte import {useStyleProps} from '../utils/styleProps'; export interface SpectrumAlertDialogProps extends DOMProps, StyleProps { - /** The [visual style](https://spectrum.adobe.com/page/alert-dialog/#Options) of the AlertDialog. */ + /** The [visual style](https://spectrum.adobe.com/page/alert-dialog/#Options) of the AlertDialog. */ variant?: 'confirmation' | 'information' | 'destructive' | 'error' | 'warning'; /** The title of the AlertDialog. */ title: string; @@ -58,7 +58,8 @@ export interface SpectrumAlertDialogProps extends DOMProps, StyleProps { } /** - * AlertDialogs are a specific type of Dialog. They display important information that users need to acknowledge. + * AlertDialogs are a specific type of Dialog. They display important information that users need to + * acknowledge. */ export const AlertDialog = forwardRef(function AlertDialog( props: SpectrumAlertDialogProps, diff --git a/packages/@adobe/react-spectrum/src/dialog/Dialog.tsx b/packages/@adobe/react-spectrum/src/dialog/Dialog.tsx index a5df756202f..4bdcc4f298c 100644 --- a/packages/@adobe/react-spectrum/src/dialog/Dialog.tsx +++ b/packages/@adobe/react-spectrum/src/dialog/Dialog.tsx @@ -49,8 +49,9 @@ let sizeMap = { }; /** - * Dialogs are windows containing contextual information, tasks, or workflows that appear over the user interface. - * Depending on the kind of Dialog, further interactions may be blocked until the Dialog is acknowledged. + * Dialogs are windows containing contextual information, tasks, or workflows that appear over the + * user interface. Depending on the kind of Dialog, further interactions may be blocked until the + * Dialog is acknowledged. */ export const Dialog = React.forwardRef(function Dialog(props: SpectrumDialogProps, ref: DOMRef) { props = useSlotProps(props, 'dialog'); diff --git a/packages/@adobe/react-spectrum/src/dialog/DialogContainer.tsx b/packages/@adobe/react-spectrum/src/dialog/DialogContainer.tsx index f0b1cd5ee4c..7891562c6df 100644 --- a/packages/@adobe/react-spectrum/src/dialog/DialogContainer.tsx +++ b/packages/@adobe/react-spectrum/src/dialog/DialogContainer.tsx @@ -22,10 +22,14 @@ export interface SpectrumDialogContainerProps { onDismiss: () => void; /** * The type of Dialog that should be rendered. See the visual options below for examples of each. + * * @default 'modal' */ type?: 'modal' | 'fullscreen' | 'fullscreenTakeover'; - /** Whether the Dialog is dismissable. See the [Dialog docs](Dialog.html#dismissable-dialogs) for more details. */ + /** + * Whether the Dialog is dismissable. See the [Dialog docs](Dialog.html#dismissable-dialogs) for + * more details. + */ isDismissable?: boolean; /** Whether pressing the escape key to close the dialog should be disabled. */ isKeyboardDismissDisabled?: boolean; diff --git a/packages/@adobe/react-spectrum/src/dialog/DialogTrigger.tsx b/packages/@adobe/react-spectrum/src/dialog/DialogTrigger.tsx index 789d30fdf0e..2df9be8d68f 100644 --- a/packages/@adobe/react-spectrum/src/dialog/DialogTrigger.tsx +++ b/packages/@adobe/react-spectrum/src/dialog/DialogTrigger.tsx @@ -29,20 +29,31 @@ import {useOverlayTrigger} from 'react-aria/useOverlayTrigger'; export type SpectrumDialogClose = (close: () => void) => ReactElement; export interface SpectrumDialogTriggerProps extends OverlayTriggerProps, PositionProps { - /** The Dialog and its trigger element. See the DialogTrigger [Content section](#content) for more information on what to provide as children. */ + /** + * The Dialog and its trigger element. See the DialogTrigger [Content section](#content) for more + * information on what to provide as children. + */ children: [ReactElement, SpectrumDialogClose | ReactElement]; /** - * The type of Dialog that should be rendered. See the DialogTrigger [types section](#dialog-types) for an explanation on each. + * The type of Dialog that should be rendered. See the DialogTrigger [types + * section](#dialog-types) for an explanation on each. + * * @default 'modal' */ type?: 'modal' | 'popover' | 'tray' | 'fullscreen' | 'fullscreenTakeover'; - /** The type of Dialog that should be rendered when on a mobile device. See DialogTrigger [types section](#dialog-types) for an explanation on each. */ + /** + * The type of Dialog that should be rendered when on a mobile device. See DialogTrigger [types + * section](#dialog-types) for an explanation on each. + */ mobileType?: 'modal' | 'tray' | 'fullscreen' | 'fullscreenTakeover'; /** * Whether a popover type Dialog's arrow should be hidden. */ hideArrow?: boolean; - /** The ref of the element the Dialog should visually attach itself to. Defaults to the trigger button if not defined. */ + /** + * The ref of the element the Dialog should visually attach itself to. Defaults to the trigger + * button if not defined. + */ targetRef?: RefObject; /** Whether a modal type Dialog should be dismissable. */ isDismissable?: boolean; @@ -171,9 +182,9 @@ DialogTrigger.getCollectionNode = function* (props: SpectrumDialogTriggerProps) }; /** - * DialogTrigger serves as a wrapper around a Dialog and its associated trigger, linking the Dialog's - * open state with the trigger's press state. Additionally, it allows you to customize the type and - * positioning of the Dialog. + * DialogTrigger serves as a wrapper around a Dialog and its associated trigger, linking the + * Dialog's open state with the trigger's press state. Additionally, it allows you to customize the + * type and positioning of the Dialog. */ // We don't want getCollectionNode to show up in the type definition diff --git a/packages/@adobe/react-spectrum/src/divider/Divider.tsx b/packages/@adobe/react-spectrum/src/divider/Divider.tsx index 5d7fc82f936..883cacbbf32 100644 --- a/packages/@adobe/react-spectrum/src/divider/Divider.tsx +++ b/packages/@adobe/react-spectrum/src/divider/Divider.tsx @@ -22,18 +22,21 @@ import {useStyleProps} from '../utils/styleProps'; export interface SpectrumDividerProps extends DOMProps, AriaLabelingProps, StyleProps { /** * How thick the Divider should be. + * * @default 'L' */ size?: 'S' | 'M' | 'L'; /** * The axis the Divider should align with. + * * @default 'horizontal' */ orientation?: Orientation; /** * A slot to place the divider in. + * * @default 'divider' */ slot?: string; diff --git a/packages/@adobe/react-spectrum/src/dnd/useDragAndDrop.ts b/packages/@adobe/react-spectrum/src/dnd/useDragAndDrop.ts index a8b53bd1502..284146dfd35 100644 --- a/packages/@adobe/react-spectrum/src/dnd/useDragAndDrop.ts +++ b/packages/@adobe/react-spectrum/src/dnd/useDragAndDrop.ts @@ -92,7 +92,7 @@ interface DropHooks { } export interface DragAndDropHooks { - /** Drag and drop hooks for the collection element. */ + /** Drag and drop hooks for the collection element. */ dragAndDropHooks: DragHooks & DropHooks & { isVirtualDragging?: () => boolean; @@ -105,16 +105,22 @@ export interface DragAndDropOptions Omit, Omit { /** - * A function that returns the items being dragged. If not specified, we assume that the collection is not draggable. + * A function that returns the items being dragged. If not specified, we assume that the + * collection is not draggable. + * * @default () => [] */ getItems?: (keys: Set, items: T[]) => DragItem[]; - /** Provide a custom drag preview. `draggedKey` represents the key of the item the user actually dragged. */ + /** + * Provide a custom drag preview. `draggedKey` represents the key of the item the user actually + * dragged. + */ renderPreview?: (keys: Set, draggedKey: Key) => JSX.Element; } /** - * Provides the hooks required to enable drag and drop behavior for a drag and drop compatible React Spectrum component. + * Provides the hooks required to enable drag and drop behavior for a drag and drop compatible React + * Spectrum component. */ export function useDragAndDrop(options: DragAndDropOptions): DragAndDropHooks { let dragAndDropHooks = useMemo(() => { diff --git a/packages/@adobe/react-spectrum/src/form/Form.tsx b/packages/@adobe/react-spectrum/src/form/Form.tsx index 55b64747f73..cb39033eb15 100644 --- a/packages/@adobe/react-spectrum/src/form/Form.tsx +++ b/packages/@adobe/react-spectrum/src/form/Form.tsx @@ -49,6 +49,7 @@ export interface SpectrumFormProps isReadOnly?: boolean; /** * Whether the Form elements should display their "valid" or "invalid" visual styling. + * * @default 'valid' */ validationState?: ValidationState; @@ -56,6 +57,7 @@ export interface SpectrumFormProps * Whether to use native HTML form validation to prevent form submission * when a field value is missing or invalid, or mark fields as required * or invalid via ARIA. + * * @default 'aria' */ validationBehavior?: 'aria' | 'native'; @@ -87,7 +89,8 @@ const formPropNames = new Set([ ]); /** - * Forms allow users to enter data that can be submitted while providing alignment and styling for form fields. + * Forms allow users to enter data that can be submitted while providing alignment and styling for + * form fields. */ export const Form = React.forwardRef(function Form( props: SpectrumFormProps, diff --git a/packages/@adobe/react-spectrum/src/icon/Icon.tsx b/packages/@adobe/react-spectrum/src/icon/Icon.tsx index 0f4e75ff667..838bcefab99 100644 --- a/packages/@adobe/react-spectrum/src/icon/Icon.tsx +++ b/packages/@adobe/react-spectrum/src/icon/Icon.tsx @@ -35,6 +35,7 @@ export interface IconProps extends DOMProps, AriaLabelingProps, StyleProps { size?: 'XXS' | 'XS' | 'S' | 'M' | 'L' | 'XL' | 'XXL'; /** * A slot to place the icon in. + * * @default 'icon' */ slot?: string; @@ -60,7 +61,8 @@ const iconStyleProps: StyleHandlers = { }; /** - * Spectrum icons are clear, minimal, and consistent across platforms. They follow the focused and rational principles of the design system in both metaphor and style. + * Spectrum icons are clear, minimal, and consistent across platforms. They follow the focused and + * rational principles of the design system in both metaphor and style. */ export function Icon(props: IconProps): JSX.Element { props = useSlotProps(props, 'icon'); diff --git a/packages/@adobe/react-spectrum/src/icon/Illustration.tsx b/packages/@adobe/react-spectrum/src/icon/Illustration.tsx index fdfe81fe5b3..71ca03ddb06 100644 --- a/packages/@adobe/react-spectrum/src/icon/Illustration.tsx +++ b/packages/@adobe/react-spectrum/src/icon/Illustration.tsx @@ -27,6 +27,7 @@ export interface IllustrationProps extends DOMProps, AriaLabelingProps, StylePro children: ReactElement; /** * A slot to place the illustration in. + * * @default 'illustration' */ slot?: string; diff --git a/packages/@adobe/react-spectrum/src/image/Image.tsx b/packages/@adobe/react-spectrum/src/image/Image.tsx index 0845f60e630..209e5f61134 100644 --- a/packages/@adobe/react-spectrum/src/image/Image.tsx +++ b/packages/@adobe/react-spectrum/src/image/Image.tsx @@ -35,11 +35,13 @@ export interface ImageProps { */ objectFit?: any; // move to styleProps for images and type better /** - * Called if an error occurs while loading or rendering an image, see [Image loading errors](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#image_loading_errors). + * Called if an error occurs while loading or rendering an image, see [Image loading + * errors](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#image_loading_errors). */ onError?: ReactEventHandler; /** - * Called when the image has successfully loaded, see [load event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/load_event). + * Called when the image has successfully loaded, see [load + * event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/load_event). */ onLoad?: ReactEventHandler; /** @@ -52,6 +54,7 @@ export interface ImageProps { export interface SpectrumImageProps extends ImageProps, DOMProps, StyleProps { /** * A slot to place the image in. + * * @default 'image' */ slot?: string; diff --git a/packages/@adobe/react-spectrum/src/inlinealert/InlineAlert.tsx b/packages/@adobe/react-spectrum/src/inlinealert/InlineAlert.tsx index 6b823bf38f5..937c2183b5e 100644 --- a/packages/@adobe/react-spectrum/src/inlinealert/InlineAlert.tsx +++ b/packages/@adobe/react-spectrum/src/inlinealert/InlineAlert.tsx @@ -31,6 +31,7 @@ import {useStyleProps} from '../utils/styleProps'; export interface SpectrumInlineAlertProps extends DOMProps, StyleProps { /** * The [visual style](https://spectrum.adobe.com/page/in-line-alert/#Options) of the Inline Alert. + * * @default 'neutral' */ variant?: 'neutral' | 'info' | 'positive' | 'notice' | 'negative'; @@ -52,8 +53,8 @@ let ICONS = { }; /** - * Inline alerts display a non-modal message associated with objects in a view. - * These are often used in form validation, providing a place to aggregate feedback related to multiple fields. + * Inline alerts display a non-modal message associated with objects in a view. These are often used + * in form validation, providing a place to aggregate feedback related to multiple fields. */ export const InlineAlert = React.forwardRef(function InlineAlert( props: SpectrumInlineAlertProps, diff --git a/packages/@adobe/react-spectrum/src/label/HelpText.tsx b/packages/@adobe/react-spectrum/src/label/HelpText.tsx index 6c077626f7f..4040bc3120f 100644 --- a/packages/@adobe/react-spectrum/src/label/HelpText.tsx +++ b/packages/@adobe/react-spectrum/src/label/HelpText.tsx @@ -39,7 +39,8 @@ interface HelpTextProps } /** - * Help text provides either an informative description or an error message that gives more context about what a user needs to input. It's commonly used in forms. + * Help text provides either an informative description or an error message that gives more context + * about what a user needs to input. It's commonly used in forms. */ export const HelpText = React.forwardRef(function HelpText( props: HelpTextProps, diff --git a/packages/@adobe/react-spectrum/src/labeledvalue/LabeledValue.tsx b/packages/@adobe/react-spectrum/src/labeledvalue/LabeledValue.tsx index 42e8f964b4b..7a8c88da9f2 100644 --- a/packages/@adobe/react-spectrum/src/labeledvalue/LabeledValue.tsx +++ b/packages/@adobe/react-spectrum/src/labeledvalue/LabeledValue.tsx @@ -114,7 +114,8 @@ type SpectrumLabeledValueTypes = export type SpectrumLabeledValueProps = LabeledValueProps & LabeledValueBaseProps; /** - * A LabeledValue displays a non-editable value with a label. It formats numbers, dates, times, and lists according to the user's locale. + * A LabeledValue displays a non-editable value with a label. It formats numbers, dates, times, and + * lists according to the user's locale. */ export const LabeledValue = React.forwardRef(function LabeledValue< T extends SpectrumLabeledValueTypes diff --git a/packages/@adobe/react-spectrum/src/layout/Grid.tsx b/packages/@adobe/react-spectrum/src/layout/Grid.tsx index 944e776e74a..e2e1d74f209 100644 --- a/packages/@adobe/react-spectrum/src/layout/Grid.tsx +++ b/packages/@adobe/react-spectrum/src/layout/Grid.tsx @@ -67,6 +67,7 @@ export const Grid = forwardRef(function Grid(props: GridProps, ref: DOMRef, Style children: ReactNode; /** * The [visual style](https://spectrum.adobe.com/page/link/#Options) of the link. + * * @default 'primary' */ variant?: 'primary' | 'secondary' | 'overBackground'; diff --git a/packages/@adobe/react-spectrum/src/list/ListView.tsx b/packages/@adobe/react-spectrum/src/list/ListView.tsx index b78836d9a5c..65a7baa0b76 100644 --- a/packages/@adobe/react-spectrum/src/list/ListView.tsx +++ b/packages/@adobe/react-spectrum/src/list/ListView.tsx @@ -66,27 +66,33 @@ export interface SpectrumListViewProps Omit { /** * Sets the amount of vertical padding within each cell. + * * @default 'regular' */ density?: 'compact' | 'regular' | 'spacious'; /** Whether the ListView should be displayed with a quiet style. */ isQuiet?: boolean; - /** The current loading state of the ListView. Determines whether or not the progress circle should be shown. */ + /** + * The current loading state of the ListView. Determines whether or not the progress circle should + * be shown. + */ loadingState?: LoadingState; /** * Sets the text behavior for the row contents. + * * @default 'truncate' */ overflowMode?: 'truncate' | 'wrap'; /** Sets what the ListView should render when there is no content to display. */ renderEmptyState?: () => JSX.Element; /** - * Handler that is called when a user performs an action on an item. The exact user event depends on - * the collection's `selectionStyle` prop and the interaction modality. + * Handler that is called when a user performs an action on an item. The exact user event depends + * on the collection's `selectionStyle` prop and the interaction modality. */ onAction?: (key: Key) => void; /** - * The drag and drop hooks returned by `useDragAndDrop` used to enable drag and drop behavior for the ListView. + * The drag and drop hooks returned by `useDragAndDrop` used to enable drag and drop behavior for + * the ListView. */ dragAndDropHooks?: DragAndDropHooks>['dragAndDropHooks']; } @@ -140,7 +146,8 @@ function useListLayout( } /** - * A ListView displays a list of interactive items, and allows a user to navigate, select, or perform an action. + * A ListView displays a list of interactive items, and allows a user to navigate, select, or + * perform an action. */ export const ListView = React.forwardRef(function ListView( props: SpectrumListViewProps, diff --git a/packages/@adobe/react-spectrum/src/menu/ActionMenu.tsx b/packages/@adobe/react-spectrum/src/menu/ActionMenu.tsx index cd74715043f..8242788aa61 100644 --- a/packages/@adobe/react-spectrum/src/menu/ActionMenu.tsx +++ b/packages/@adobe/react-spectrum/src/menu/ActionMenu.tsx @@ -38,7 +38,10 @@ export interface SpectrumActionMenuProps AriaLabelingProps { /** Whether the button is disabled. */ isDisabled?: boolean; - /** Whether the button should be displayed with a [quiet style](https://spectrum.adobe.com/page/action-button/#Quiet). */ + /** + * Whether the button should be displayed with a [quiet + * style](https://spectrum.adobe.com/page/action-button/#Quiet). + */ isQuiet?: boolean; /** Whether the element should receive focus on render. */ autoFocus?: boolean; diff --git a/packages/@adobe/react-spectrum/src/menu/MenuTrigger.tsx b/packages/@adobe/react-spectrum/src/menu/MenuTrigger.tsx index c6a3545ffdc..28e9b389f27 100644 --- a/packages/@adobe/react-spectrum/src/menu/MenuTrigger.tsx +++ b/packages/@adobe/react-spectrum/src/menu/MenuTrigger.tsx @@ -33,21 +33,25 @@ export interface SpectrumMenuTriggerProps extends MenuTriggerProps { children: ReactElement[]; /** * Alignment of the menu relative to the trigger. + * * @default 'start' */ align?: Alignment; /** * Where the Menu opens relative to its trigger. + * * @default 'bottom' */ direction?: 'bottom' | 'top' | 'left' | 'right' | 'start' | 'end'; /** * Whether the menu should automatically flip direction when space is limited. + * * @default true */ shouldFlip?: boolean; /** * Whether the Menu closes when a selection is made. + * * @default true */ closeOnSelect?: boolean; diff --git a/packages/@adobe/react-spectrum/src/meter/Meter.tsx b/packages/@adobe/react-spectrum/src/meter/Meter.tsx index 226253e5903..3244a15011d 100644 --- a/packages/@adobe/react-spectrum/src/meter/Meter.tsx +++ b/packages/@adobe/react-spectrum/src/meter/Meter.tsx @@ -20,6 +20,7 @@ import {useMeter} from 'react-aria/useMeter'; export interface SpectrumMeterProps extends SpectrumProgressBarBaseProps { /** * The [visual style](https://spectrum.adobe.com/page/meter/#Options) of the Meter. + * * @default 'informative' */ variant?: 'informative' | 'positive' | 'warning' | 'critical'; diff --git a/packages/@adobe/react-spectrum/src/numberfield/NumberField.tsx b/packages/@adobe/react-spectrum/src/numberfield/NumberField.tsx index 784a6d76d16..e8bdf7bb3a1 100644 --- a/packages/@adobe/react-spectrum/src/numberfield/NumberField.tsx +++ b/packages/@adobe/react-spectrum/src/numberfield/NumberField.tsx @@ -48,13 +48,15 @@ export interface SpectrumNumberFieldProps isQuiet?: boolean; /** * Whether to hide the increment and decrement buttons. + * * @default false */ hideStepper?: boolean; } /** - * NumberFields allow users to enter a number, and increment or decrement the value using stepper buttons. + * NumberFields allow users to enter a number, and increment or decrement the value using stepper + * buttons. */ export const NumberField = React.forwardRef(function NumberField( props: SpectrumNumberFieldProps, diff --git a/packages/@adobe/react-spectrum/src/overlays/Popover.tsx b/packages/@adobe/react-spectrum/src/overlays/Popover.tsx index 18e63ea9eed..ff8f1aaaae6 100644 --- a/packages/@adobe/react-spectrum/src/overlays/Popover.tsx +++ b/packages/@adobe/react-spectrum/src/overlays/Popover.tsx @@ -61,11 +61,11 @@ interface ArrowProps { } /** - * Arrow placement can be done pointing right or down because those paths start at 0, x or y. Because the - * other two don't, they start at a fractional pixel value, it introduces rounding differences between browsers and - * between display types (retina with subpixels vs not retina). By flipping them with CSS we can ensure that - * the path always starts at 0 so that it perfectly overlaps the popover's border. - * See bottom of file for more explanation. + * Arrow placement can be done pointing right or down because those paths start at 0, x or y. + * Because the other two don't, they start at a fractional pixel value, it introduces rounding + * differences between browsers and between display types (retina with subpixels vs not retina). By + * flipping them with CSS we can ensure that the path always starts at 0 so that it perfectly + * overlaps the popover's border. See bottom of file for more explanation. */ let arrowPlacement = { left: 'right', @@ -262,15 +262,14 @@ function Arrow(props: ArrowProps) { } /** - * More explanation on popover tips. - * - I tried changing the calculation of the popover placement in an effort to get it squarely onto the pixel grid. - * This did not work because the problem was in the svg partial pixel end of the path in the popover right and popover bottom. - * - I tried creating an extra 'bandaid' path that matched the background color and would overlap the popover border. - * This didn't work because the border on the svg triangle didn't extend all the way to match nicely with the popover border. - * - I tried getting the client bounding box and setting the svg to that partial pixel value - * This didn't work because again the issue was inside the svg - * - I didn't try drawing the svg backwards - * This could still be tried - * - I tried changing the calculation of the popover placement AND the svg height/width so that they were all rounded - * This seems to have done the trick. + * More explanation on popover tips. - I tried changing the calculation of the popover placement in + * an effort to get it squarely onto the pixel grid. This did not work because the problem was in + * the svg partial pixel end of the path in the popover right and popover bottom. - I tried creating + * an extra 'bandaid' path that matched the background color and would overlap the popover border. + * This didn't work because the border on the svg triangle didn't extend all the way to match nicely + * with the popover border. - I tried getting the client bounding box and setting the svg to that + * partial pixel value This didn't work because again the issue was inside the svg - I didn't try + * drawing the svg backwards This could still be tried - I tried changing the calculation of the + * popover placement AND the svg height/width so that they were all rounded This seems to have done + * the trick. */ diff --git a/packages/@adobe/react-spectrum/src/picker/Picker.tsx b/packages/@adobe/react-spectrum/src/picker/Picker.tsx index a98aa9b3cce..b5db50eb030 100644 --- a/packages/@adobe/react-spectrum/src/picker/Picker.tsx +++ b/packages/@adobe/react-spectrum/src/picker/Picker.tsx @@ -71,28 +71,36 @@ export interface SpectrumPickerProps StyleProps { /** Whether the textfield should be displayed with a quiet style. */ isQuiet?: boolean; - /** Alignment of the menu relative to the input target. + /** + * Alignment of the menu relative to the input target. + * * @default 'start' */ align?: Alignment; /** * Direction the menu will render relative to the Picker. + * * @default 'bottom' */ direction?: 'bottom' | 'top'; /** * Whether the menu should automatically flip direction when space is limited. + * * @default true */ shouldFlip?: boolean; - /** Width of the menu. By default, matches width of the trigger. Note that the minimum width of the dropdown is always equal to the trigger's width. */ + /** + * Width of the menu. By default, matches width of the trigger. Note that the minimum width of the + * dropdown is always equal to the trigger's width. + */ menuWidth?: DimensionValue; /** Whether the element should receive focus on render. */ autoFocus?: boolean; } /** - * Pickers allow users to choose a single option from a collapsible list of options when space is limited. + * Pickers allow users to choose a single option from a collapsible list of options when space is + * limited. */ // forwardRef doesn't support generic parameters, so cast the result to the correct type // https://stackoverflow.com/questions/58469229/react-with-typescript-generics-while-using-react-forwardref diff --git a/packages/@adobe/react-spectrum/src/progress/ProgressBar.tsx b/packages/@adobe/react-spectrum/src/progress/ProgressBar.tsx index 81c917a884e..5b0f4953444 100644 --- a/packages/@adobe/react-spectrum/src/progress/ProgressBar.tsx +++ b/packages/@adobe/react-spectrum/src/progress/ProgressBar.tsx @@ -18,8 +18,8 @@ import styles from '@adobe/spectrum-css-temp/components/barloader/vars.css'; import {useProgressBar} from 'react-aria/useProgressBar'; /** - * ProgressBars show the progression of a system operation: downloading, uploading, processing, etc., in a visual way. - * They can represent either determinate or indeterminate progress. + * ProgressBars show the progression of a system operation: downloading, uploading, processing, + * etc., in a visual way. They can represent either determinate or indeterminate progress. */ export const ProgressBar = React.forwardRef(function ProgressBar( props: SpectrumProgressBarProps, diff --git a/packages/@adobe/react-spectrum/src/progress/ProgressBarBase.tsx b/packages/@adobe/react-spectrum/src/progress/ProgressBarBase.tsx index 94efc05deff..6a5bd6f8a69 100644 --- a/packages/@adobe/react-spectrum/src/progress/ProgressBarBase.tsx +++ b/packages/@adobe/react-spectrum/src/progress/ProgressBarBase.tsx @@ -23,15 +23,20 @@ import {useStyleProps} from '../utils/styleProps'; export interface SpectrumProgressBarBaseProps extends AriaProgressBarBaseProps, StyleProps { /** * How thick the bar should be. + * * @default 'L' */ size?: 'S' | 'L'; /** * The label's overall position relative to the element it is labeling. + * * @default 'top' */ labelPosition?: LabelPosition; - /** Whether the value's label is displayed. True by default if there's a label, false by default if not. */ + /** + * Whether the value's label is displayed. True by default if there's a label, false by default if + * not. + */ showValueLabel?: boolean; } @@ -39,7 +44,9 @@ export interface SpectrumProgressBarProps extends SpectrumProgressBarBaseProps, /** The static color style to apply. Useful when the button appears over a color background. */ staticColor?: 'white' | 'black'; /** - * The [visual style](https://spectrum.adobe.com/page/progress-bar/#Over-background-variant) of the ProgressBar. + * The [visual style](https://spectrum.adobe.com/page/progress-bar/#Over-background-variant) of + * the ProgressBar. + * * @deprecated - use staticColor instead. */ variant?: 'overBackground'; diff --git a/packages/@adobe/react-spectrum/src/progress/ProgressCircle.tsx b/packages/@adobe/react-spectrum/src/progress/ProgressCircle.tsx index 0c081adce90..9b0c82c1146 100644 --- a/packages/@adobe/react-spectrum/src/progress/ProgressCircle.tsx +++ b/packages/@adobe/react-spectrum/src/progress/ProgressCircle.tsx @@ -22,16 +22,19 @@ import {useStyleProps} from '../utils/styleProps'; export interface ProgressCircleProps { /** * The current value (controlled). + * * @default 0 */ value?: number; /** * The smallest value allowed for the input. + * * @default 0 */ minValue?: number; /** * The largest value allowed for the input. + * * @default 100 */ maxValue?: number; @@ -45,13 +48,15 @@ export interface AriaProgressCircleProps extends ProgressCircleProps, DOMProps, export interface SpectrumProgressCircleProps extends AriaProgressCircleProps, StyleProps { /** * What the ProgressCircle's diameter should be. + * * @default 'M' */ size?: 'S' | 'M' | 'L'; /** The static color style to apply. Useful when the button appears over a color background. */ staticColor?: 'white' | 'black'; /** - * The [visual style](https://spectrum.adobe.com/page/progress-circle/#Over-background-variant) of the ProgressCircle. + * The [visual style](https://spectrum.adobe.com/page/progress-circle/#Over-background-variant) of + * the ProgressCircle. * * @deprecated - use staticColor instead. */ @@ -59,8 +64,8 @@ export interface SpectrumProgressCircleProps extends AriaProgressCircleProps, St } /** - * ProgressCircles show the progression of a system operation such as downloading, uploading, or processing, in a visual way. - * They can represent determinate or indeterminate progress. + * ProgressCircles show the progression of a system operation such as downloading, uploading, or + * processing, in a visual way. They can represent determinate or indeterminate progress. */ export const ProgressCircle = React.forwardRef(function ProgressCircle( props: SpectrumProgressCircleProps, diff --git a/packages/@adobe/react-spectrum/src/provider/Provider.tsx b/packages/@adobe/react-spectrum/src/provider/Provider.tsx index 7b12903afca..fe7e6ac0535 100644 --- a/packages/@adobe/react-spectrum/src/provider/Provider.tsx +++ b/packages/@adobe/react-spectrum/src/provider/Provider.tsx @@ -204,8 +204,8 @@ const ProviderWrapper = React.forwardRef(function ProviderWrapper( }); /** - * Returns the various settings and styles applied by the nearest parent Provider. - * Properties explicitly set by the nearest parent Provider override those provided by preceeding Providers. + * Returns the various settings and styles applied by the nearest parent Provider. Properties + * explicitly set by the nearest parent Provider override those provided by preceeding Providers. */ export function useProvider(): ProviderContext { let context = useContext(Context); diff --git a/packages/@adobe/react-spectrum/src/provider/types.ts b/packages/@adobe/react-spectrum/src/provider/types.ts index af3f41f9027..33be39e2533 100644 --- a/packages/@adobe/react-spectrum/src/provider/types.ts +++ b/packages/@adobe/react-spectrum/src/provider/types.ts @@ -75,6 +75,7 @@ export interface ProviderProps extends ContextProps, DOMProps, StyleProps { colorScheme?: ColorScheme; /** * The default color scheme if no operating system setting is available. + * * @default 'light' */ defaultColorScheme?: ColorScheme; @@ -83,19 +84,22 @@ export interface ProviderProps extends ContextProps, DOMProps, StyleProps { */ scale?: Scale; /** - * The locale for your application as a [BCP 47](https://www.ietf.org/rfc/bcp/bcp47.txt) language code. - * Defaults to the browser/OS language setting. + * The locale for your application as a [BCP 47](https://www.ietf.org/rfc/bcp/bcp47.txt) language + * code. Defaults to the browser/OS language setting. + * * @default 'en-US' */ locale?: string; /** * The breakpoints for styleProps. * Do not use `base` property. - * @default {S:380,M:768,L:1024} + * + * @default { S: 380, M: 768, L: 1024 } */ breakpoints?: Breakpoints; /** - * Provides a client side router to all nested React Spectrum links to enable client side navigation. + * Provides a client side router to all nested React Spectrum links to enable client side + * navigation. */ router?: Router; } diff --git a/packages/@adobe/react-spectrum/src/slider/RangeSlider.tsx b/packages/@adobe/react-spectrum/src/slider/RangeSlider.tsx index 63309b80bd5..c250e70feb0 100644 --- a/packages/@adobe/react-spectrum/src/slider/RangeSlider.tsx +++ b/packages/@adobe/react-spectrum/src/slider/RangeSlider.tsx @@ -29,11 +29,13 @@ import {useLocalizedStringFormatter} from 'react-aria/useLocalizedStringFormatte export interface SpectrumRangeSliderProps extends SpectrumBarSliderBase> { /** - * The name of the start input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). + * The name of the start input element, used when submitting an HTML form. See + * [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). */ startName?: string; /** - * The name of the end input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). + * The name of the end input element, used when submitting an HTML form. See + * [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). */ endName?: string; /** @@ -45,7 +47,8 @@ export interface SpectrumRangeSliderProps extends SpectrumBarSliderBase, InputDOMProps { /** * Whether a fill color is shown between the start of the slider and the current value. + * * @see https://spectrum.adobe.com/page/slider/#Fill. */ isFilled?: boolean; /** * The offset from which to start the fill. + * * @see https://spectrum.adobe.com/page/slider/#Fill-start. */ fillOffset?: number; /** - * The background of the track, specified as the stops for a CSS background: `linear-gradient(to right/left, ...trackGradient)`. - * @example trackGradient={['red', 'green']} - * @example trackGradient={['red 20%', 'green 40%']} + * The background of the track, specified as the stops for a CSS background: `linear-gradient(to + * right/left, ...trackGradient)`. + * + * @example + * trackGradient={['red', 'green']} + * + * @example + * trackGradient={['red 20%', 'green 40%']} + * * @see https://spectrum.adobe.com/page/slider/#Gradient. */ trackGradient?: string[]; } /** - * Sliders allow users to quickly select a value within a range. They should be used when the upper and lower bounds to the range are invariable. + * Sliders allow users to quickly select a value within a range. They should be used when the upper + * and lower bounds to the range are invariable. */ export const Slider = React.forwardRef(function Slider( props: SpectrumSliderProps, diff --git a/packages/@adobe/react-spectrum/src/slider/SliderBase.tsx b/packages/@adobe/react-spectrum/src/slider/SliderBase.tsx index 4c232b87cef..5b855af4425 100644 --- a/packages/@adobe/react-spectrum/src/slider/SliderBase.tsx +++ b/packages/@adobe/react-spectrum/src/slider/SliderBase.tsx @@ -30,12 +30,19 @@ export interface SpectrumBarSliderBase extends AriaSliderProps, ValueBase< formatOptions?: Intl.NumberFormatOptions; /** * The label's overall position relative to the element it is labeling. + * * @default 'top' */ labelPosition?: LabelPosition; - /** Whether the value's label is displayed. True by default if there's a `label`, false by default if not. */ + /** + * Whether the value's label is displayed. True by default if there's a `label`, false by default + * if not. + */ showValueLabel?: boolean; - /** A function that returns the content to display as the value's label. Overrides default formatted number. */ + /** + * A function that returns the content to display as the value's label. Overrides default + * formatted number. + */ getValueLabel?: (value: T) => string; /** * A ContextualHelp element to place next to the label. diff --git a/packages/@adobe/react-spectrum/src/steplist/StepList.tsx b/packages/@adobe/react-spectrum/src/steplist/StepList.tsx index d04e4036e2e..a5c9d793cda 100644 --- a/packages/@adobe/react-spectrum/src/steplist/StepList.tsx +++ b/packages/@adobe/react-spectrum/src/steplist/StepList.tsx @@ -26,16 +26,19 @@ import {useStyleProps} from '../utils/styleProps'; export interface SpectrumStepListProps extends AriaStepListProps, StyleProps { /** * Whether the step list should be displayed with a emphasized style. + * * @default false */ isEmphasized?: boolean; /** * The orientation of the step list. + * * @default 'horizontal' */ orientation?: Orientation; /** * The size of the step list. + * * @default 'M' */ size?: 'S' | 'M' | 'L' | 'XL'; diff --git a/packages/@adobe/react-spectrum/src/table/TableView.tsx b/packages/@adobe/react-spectrum/src/table/TableView.tsx index c99369852b4..13bfe9b5c94 100644 --- a/packages/@adobe/react-spectrum/src/table/TableView.tsx +++ b/packages/@adobe/react-spectrum/src/table/TableView.tsx @@ -45,11 +45,13 @@ export interface SpectrumTableProps StyleProps { /** * Sets the amount of vertical padding within each cell. + * * @default 'regular' */ density?: 'compact' | 'regular' | 'spacious'; /** * Sets the overflow behavior for the cell contents. + * * @default 'truncate' */ overflowMode?: 'wrap' | 'truncate'; @@ -59,7 +61,8 @@ export interface SpectrumTableProps renderEmptyState?: () => JSX.Element; /** * Whether `disabledKeys` applies to all interactions, or only selection. - * @default "selection" + * + * @default 'selection' */ disabledBehavior?: DisabledBehavior; /** Handler that is called when a user performs an action on a row. */ @@ -80,41 +83,52 @@ export interface SpectrumTableProps */ onResizeEnd?: (widths: Map) => void; /** - * The drag and drop hooks returned by `useDragAndDrop` used to enable drag and drop behavior for the TableView. + * The drag and drop hooks returned by `useDragAndDrop` used to enable drag and drop behavior for + * the TableView. + * * @version beta */ dragAndDropHooks?: DragAndDropHooks>['dragAndDropHooks']; /** - * Whether the TableView should support expandable rows. Requires the feature flag to be enabled first, see https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows. - * @version alpha + * Whether the TableView should support expandable rows. Requires the feature flag to be enabled + * first, see https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows. + * * @private + * @version alpha */ UNSTABLE_allowsExpandableRows?: boolean; /** * The currently expanded keys in the collection (controlled). Requires the feature flag to be - * enabled along with UNSTABLE_allowsExpandableRows, see https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows. - * @version alpha + * enabled along with UNSTABLE_allowsExpandableRows, see + * https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows. + * * @private + * @version alpha */ UNSTABLE_expandedKeys?: 'all' | Iterable; /** * The initial expanded keys in the collection (uncontrolled). Requires the feature flag to be - * enabled along with UNSTABLE_allowsExpandableRows, see https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows. - * @version alpha + * enabled along with UNSTABLE_allowsExpandableRows, see + * https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows. + * * @private + * @version alpha */ UNSTABLE_defaultExpandedKeys?: 'all' | Iterable; /** * Handler that is called when items are expanded or collapsed. Requires the feature flag to be - * enabled along with UNSTABLE_allowsExpandableRows, see https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows. - * @version alpha + * enabled along with UNSTABLE_allowsExpandableRows, see + * https://react-spectrum.adobe.com/react-spectrum/TableView.html#expandable-rows. + * * @private + * @version alpha */ UNSTABLE_onExpandedChange?: (keys: Set) => any; } /** - * Tables are containers for displaying information. They allow users to quickly scan, sort, compare, and take action on large amounts of data. + * Tables are containers for displaying information. They allow users to quickly scan, sort, + * compare, and take action on large amounts of data. */ const TableView = React.forwardRef(function TableView( props: SpectrumTableProps, diff --git a/packages/@adobe/react-spectrum/src/table/types.ts b/packages/@adobe/react-spectrum/src/table/types.ts index afb3337cadb..d0531a16b34 100644 --- a/packages/@adobe/react-spectrum/src/table/types.ts +++ b/packages/@adobe/react-spectrum/src/table/types.ts @@ -15,6 +15,7 @@ import {ColumnProps} from 'react-stately/useTableState'; export interface SpectrumColumnProps extends ColumnProps { /** * The alignment of the column's contents relative to its allotted width. + * * @default 'start' */ align?: 'start' | 'center' | 'end'; @@ -23,9 +24,9 @@ export interface SpectrumColumnProps extends ColumnProps { /** Whether the column should render a divider between it and the next column. */ showDivider?: boolean; /** - * Whether the column should hide its header text. A tooltip with the column's header text - * will be displayed when the column header is focused instead. Note that this prop is specifically for columns - * that contain ActionButtons in place of text content. + * Whether the column should hide its header text. A tooltip with the column's header text will be + * displayed when the column header is focused instead. Note that this prop is specifically for + * columns that contain ActionButtons in place of text content. */ hideHeader?: boolean; } diff --git a/packages/@adobe/react-spectrum/src/tabs/Tabs.tsx b/packages/@adobe/react-spectrum/src/tabs/Tabs.tsx index 02dd87b50dc..b35770fd439 100644 --- a/packages/@adobe/react-spectrum/src/tabs/Tabs.tsx +++ b/packages/@adobe/react-spectrum/src/tabs/Tabs.tsx @@ -73,7 +73,10 @@ export interface SpectrumTabsProps children: ReactNode; /** The item objects for each tab, for dynamic collections. */ items?: Iterable; - /** The keys of the tabs that are disabled. These tabs cannot be selected, focused, or otherwise interacted with. */ + /** + * The keys of the tabs that are disabled. These tabs cannot be selected, focused, or otherwise + * interacted with. + */ disabledKeys?: Iterable; /** Whether the Tabs are disabled. */ isDisabled?: boolean; @@ -91,11 +94,13 @@ export interface SpectrumTabsProps onSelectionChange?: (key: Key) => void; /** * Whether tabs are activated automatically on focus or manually. + * * @default 'automatic' */ keyboardActivation?: 'automatic' | 'manual'; /** * The orientation of the tabs. + * * @default 'horizontal' */ orientation?: Orientation; @@ -120,7 +125,8 @@ interface TabsContext { const TabContext = React.createContext | null>(null); /** - * Tabs organize content into multiple sections and allow users to navigate between them. The content under the set of tabs should be related and form a coherent unit. + * Tabs organize content into multiple sections and allow users to navigate between them. The + * content under the set of tabs should be related and form a coherent unit. */ // forwardRef doesn't support generic parameters, so cast the result to the correct type // https://stackoverflow.com/questions/58469229/react-with-typescript-generics-while-using-react-forwardref @@ -348,13 +354,16 @@ function TabLine(props: TabLineProps) { } export interface SpectrumTabListProps extends DOMProps, StyleProps { - /** The tab items to display. Item keys should match the key of the corresponding `` within the `` element. */ + /** + * The tab items to display. Item keys should match the key of the corresponding `` within + * the `` element. + */ children: CollectionChildren; } /** - * A TabList is used within Tabs to group tabs that a user can switch between. - * The keys of the items within the must match up with a corresponding item inside the . + * A TabList is used within Tabs to group tabs that a user can switch between. The keys of the items + * within the must match up with a corresponding item inside the . */ export function TabList(props: SpectrumTabListProps): ReactElement { const tabContext = useContext(TabContext)!; @@ -438,13 +447,16 @@ export function TabList(props: SpectrumTabListProps): ReactElement { } export interface SpectrumTabPanelsProps extends DOMProps, StyleProps { - /** The contents of each tab. Item keys should match the key of the corresponding `` within the `` element. */ + /** + * The contents of each tab. Item keys should match the key of the corresponding `` within + * the `` element. + */ children: CollectionChildren; } /** - * TabPanels is used within Tabs as a container for the content of each tab. - * The keys of the items within the must match up with a corresponding item inside the . + * TabPanels is used within Tabs as a container for the content of each tab. The keys of the items + * within the must match up with a corresponding item inside the . */ export function TabPanels(props: SpectrumTabPanelsProps): ReactElement { const {tabState, tabProps} = useContext(TabContext)!; diff --git a/packages/@adobe/react-spectrum/src/tag/TagGroup.tsx b/packages/@adobe/react-spectrum/src/tag/TagGroup.tsx index 89d2b31b975..fcf93dad5c3 100644 --- a/packages/@adobe/react-spectrum/src/tag/TagGroup.tsx +++ b/packages/@adobe/react-spectrum/src/tag/TagGroup.tsx @@ -69,17 +69,23 @@ export interface SpectrumTagGroupProps StyleProps, Omit, Pick, 'isInvalid' | 'validationState'> { - /** The label to display on the action button. */ + /** The label to display on the action button. */ actionLabel?: string; /** Handler that is called when the action button is pressed. */ onAction?: () => void; /** Sets what the TagGroup should render when there are no tags to display. */ renderEmptyState?: () => JSX.Element; - /** Limit the number of rows initially shown. This will render a button that allows the user to expand to show all tags. */ + /** + * Limit the number of rows initially shown. This will render a button that allows the user to + * expand to show all tags. + */ maxRows?: number; } -/** Tags allow users to categorize content. They can represent keywords or people, and are grouped to describe an item or a search request. */ +/** + * Tags allow users to categorize content. They can represent keywords or people, and are grouped to + * describe an item or a search request. + */ export const TagGroup = React.forwardRef(function TagGroup( props: SpectrumTagGroupProps, ref: DOMRef diff --git a/packages/@adobe/react-spectrum/src/text/Heading.tsx b/packages/@adobe/react-spectrum/src/text/Heading.tsx index 4198214b4ba..0919a88027d 100644 --- a/packages/@adobe/react-spectrum/src/text/Heading.tsx +++ b/packages/@adobe/react-spectrum/src/text/Heading.tsx @@ -26,11 +26,13 @@ export interface HeadingProps extends DOMProps, StyleProps { children: ReactNode; /** * A slot to place the heading in. + * * @default 'heading' */ slot?: string; /** * Sets heading level, h1 through h6. + * * @default 3 */ level?: 1 | 2 | 3 | 4 | 5 | 6; diff --git a/packages/@adobe/react-spectrum/src/text/Keyboard.tsx b/packages/@adobe/react-spectrum/src/text/Keyboard.tsx index f8318670928..379e966909f 100644 --- a/packages/@adobe/react-spectrum/src/text/Keyboard.tsx +++ b/packages/@adobe/react-spectrum/src/text/Keyboard.tsx @@ -24,6 +24,7 @@ export interface KeyboardProps extends DOMProps, StyleProps { children: ReactNode; /** * A slot to place the keyboard shortcut in. + * * @default 'keyboard' */ slot?: string; diff --git a/packages/@adobe/react-spectrum/src/text/Text.tsx b/packages/@adobe/react-spectrum/src/text/Text.tsx index a3041e1a057..97c7530a06f 100644 --- a/packages/@adobe/react-spectrum/src/text/Text.tsx +++ b/packages/@adobe/react-spectrum/src/text/Text.tsx @@ -24,6 +24,7 @@ export interface TextProps extends DOMProps, StyleProps { children: ReactNode; /** * A slot to place the text in. + * * @default 'text' */ slot?: string; diff --git a/packages/@adobe/react-spectrum/src/tooltip/Tooltip.tsx b/packages/@adobe/react-spectrum/src/tooltip/Tooltip.tsx index b1d53312deb..23d2089f980 100644 --- a/packages/@adobe/react-spectrum/src/tooltip/Tooltip.tsx +++ b/packages/@adobe/react-spectrum/src/tooltip/Tooltip.tsx @@ -31,6 +31,7 @@ export interface SpectrumTooltipProps extends AriaTooltipProps, StyleProps { /** * The placement of the element with respect to its anchor element. + * * @default 'top' */ placement?: 'start' | 'end' | 'right' | 'left' | 'top' | 'bottom'; diff --git a/packages/@adobe/react-spectrum/src/tooltip/TooltipTrigger.tsx b/packages/@adobe/react-spectrum/src/tooltip/TooltipTrigger.tsx index ad1510e8430..8aea3cf9707 100644 --- a/packages/@adobe/react-spectrum/src/tooltip/TooltipTrigger.tsx +++ b/packages/@adobe/react-spectrum/src/tooltip/TooltipTrigger.tsx @@ -26,11 +26,13 @@ export interface SpectrumTooltipTriggerProps /** * The additional offset applied along the main axis between the element and its * anchor element. + * * @default 7 */ offset?: number; /** * The placement of the tooltip with respect to the trigger. + * * @default 'top' */ placement?: Placement; diff --git a/packages/@adobe/react-spectrum/src/tree/TreeView.tsx b/packages/@adobe/react-spectrum/src/tree/TreeView.tsx index 8b80b0ef33f..c473de14711 100644 --- a/packages/@adobe/react-spectrum/src/tree/TreeView.tsx +++ b/packages/@adobe/react-spectrum/src/tree/TreeView.tsx @@ -62,8 +62,8 @@ export interface SpectrumTreeViewProps /** Provides content to display when there are no items in the tree. */ renderEmptyState?: () => JSX.Element; /** - * Handler that is called when a user performs an action on an item. The exact user event depends on - * the collection's `selectionStyle` prop and the interaction modality. + * Handler that is called when a user performs an action on an item. The exact user event depends + * on the collection's `selectionStyle` prop and the interaction modality. */ onAction?: (key: Key) => void; /** diff --git a/packages/@adobe/react-spectrum/src/view/View.tsx b/packages/@adobe/react-spectrum/src/view/View.tsx index 0fe6483be67..7ad0a3de409 100644 --- a/packages/@adobe/react-spectrum/src/view/View.tsx +++ b/packages/@adobe/react-spectrum/src/view/View.tsx @@ -30,8 +30,9 @@ export interface ViewProps extends ViewStyleProps, DO } /** - * View is a general purpose container with no specific semantics that can be used for custom styling purposes. - * It supports Spectrum style props to ensure consistency with other Spectrum components. + * View is a general purpose container with no specific semantics that can be used for custom + * styling purposes. It supports Spectrum style props to ensure consistency with other Spectrum + * components. */ export const View = forwardRef(function View( props: ViewProps, diff --git a/packages/@adobe/react-spectrum/src/well/Well.tsx b/packages/@adobe/react-spectrum/src/well/Well.tsx index 7de38062070..fc69bf5a024 100644 --- a/packages/@adobe/react-spectrum/src/well/Well.tsx +++ b/packages/@adobe/react-spectrum/src/well/Well.tsx @@ -32,8 +32,9 @@ export interface SpectrumWellProps extends DOMProps, AriaLabelingProps, StylePro } /** - * A Well is a content container that displays non-editable content separate from other content on the screen. - * Often this is used to display preformatted text, such as code/markup examples on a documentation page. + * A Well is a content container that displays non-editable content separate from other content on + * the screen. Often this is used to display preformatted text, such as code/markup examples on a + * documentation page. */ export const Well = forwardRef(function Well( props: SpectrumWellProps, diff --git a/packages/@adobe/react-spectrum/stories/actiongroup/Toolbar.stories.tsx b/packages/@adobe/react-spectrum/stories/actiongroup/Toolbar.stories.tsx index 22597082dab..08a7685c1ac 100644 --- a/packages/@adobe/react-spectrum/stories/actiongroup/Toolbar.stories.tsx +++ b/packages/@adobe/react-spectrum/stories/actiongroup/Toolbar.stories.tsx @@ -38,6 +38,7 @@ export interface SpectrumToolbarProps extends AriaLabelingProps { children: ReactNode | ReactElement[]; /** * The orientation of the entire toolbar. + * * @default 'horizontal' */ orientation?: Orientation; diff --git a/packages/@adobe/react-spectrum/test/tabs/Tabs.test.js b/packages/@adobe/react-spectrum/test/tabs/Tabs.test.js index a7ef88fc9ef..5f09f928321 100644 --- a/packages/@adobe/react-spectrum/test/tabs/Tabs.test.js +++ b/packages/@adobe/react-spectrum/test/tabs/Tabs.test.js @@ -144,7 +144,7 @@ describe('Tabs', function () { expect(selectedItem).toHaveAttribute('aria-selected', 'true'); expect(arrowLeft.defaultPrevented).toBe(true); - /** prevent changing tabs for horizontal orientations in aria-selected */ + /** Prevent changing tabs for horizontal orientations in aria-selected. */ let arrowUp = createEvent.keyDown(selectedItem, {key: 'ArrowUp', code: 38, charCode: 38}); fireEvent(selectedItem, arrowUp); expect(selectedItem).toHaveAttribute('aria-selected', 'true'); diff --git a/packages/@internationalized/date/src/CalendarDate.ts b/packages/@internationalized/date/src/CalendarDate.ts index 8c0b3322a00..35ab3943c7e 100644 --- a/packages/@internationalized/date/src/CalendarDate.ts +++ b/packages/@internationalized/date/src/CalendarDate.ts @@ -122,7 +122,10 @@ export class CalendarDate { return subtract(this, duration); } - /** Returns a new `CalendarDate` with the given fields set to the provided values. Other fields will be constrained accordingly. */ + /** + * Returns a new `CalendarDate` with the given fields set to the provided values. Other fields + * will be constrained accordingly. + */ set(fields: DateFields): CalendarDate { return set(this, fields); } @@ -135,7 +138,10 @@ export class CalendarDate { return cycleDate(this, field, amount, options); } - /** Converts the date to a native JavaScript Date object, with the time set to midnight in the given time zone. */ + /** + * Converts the date to a native JavaScript Date object, with the time set to midnight in the + * given time zone. + */ toDate(timeZone: string): Date { return toDate(this, timeZone); } @@ -145,7 +151,10 @@ export class CalendarDate { return dateToString(this); } - /** Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after. */ + /** + * Compares this date with another. A negative result indicates that this date is before the given + * one, and a positive date indicates that it is after. + */ compare(b: AnyCalendarDate): number { return compareDate(this, b); } @@ -188,7 +197,10 @@ export class Time { return subtractTime(this, duration); } - /** Returns a new `Time` with the given fields set to the provided values. Other fields will be constrained accordingly. */ + /** + * Returns a new `Time` with the given fields set to the provided values. Other fields will be + * constrained accordingly. + */ set(fields: TimeFields): Time { return setTime(this, fields); } @@ -206,7 +218,10 @@ export class Time { return timeToString(this); } - /** Compares this time with another. A negative result indicates that this time is before the given one, and a positive time indicates that it is after. */ + /** + * Compares this time with another. A negative result indicates that this time is before the given + * one, and a positive time indicates that it is after. + */ compare(b: AnyTime): number { return compareTime(this, b); } @@ -333,7 +348,10 @@ export class CalendarDateTime { return subtract(this, duration); } - /** Returns a new `CalendarDateTime` with the given fields set to the provided values. Other fields will be constrained accordingly. */ + /** + * Returns a new `CalendarDateTime` with the given fields set to the provided values. Other fields + * will be constrained accordingly. + */ set(fields: DateFields & TimeFields): CalendarDateTime { return set(setTime(this, fields), fields); } @@ -368,7 +386,10 @@ export class CalendarDateTime { return dateTimeToString(this); } - /** Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after. */ + /** + * Compares this date with another. A negative result indicates that this date is before the given + * one, and a positive date indicates that it is after. + */ compare(b: CalendarDate | CalendarDateTime | ZonedDateTime): number { let res = compareDate(this, b); if (res === 0) { @@ -520,7 +541,10 @@ export class ZonedDateTime { return subtractZoned(this, duration); } - /** Returns a new `ZonedDateTime` with the given fields set to the provided values. Other fields will be constrained accordingly. */ + /** + * Returns a new `ZonedDateTime` with the given fields set to the provided values. Other fields + * will be constrained accordingly. + */ set(fields: DateFields & TimeFields, disambiguation?: Disambiguation): ZonedDateTime { return setZoned(this, fields, disambiguation); } @@ -538,7 +562,10 @@ export class ZonedDateTime { return zonedToDate(this); } - /** Converts the date to an ISO 8601 formatted string, including the UTC offset and time zone identifier. */ + /** + * Converts the date to an ISO 8601 formatted string, including the UTC offset and time zone + * identifier. + */ toString(): string { return zonedDateTimeToString(this); } @@ -548,7 +575,10 @@ export class ZonedDateTime { return this.toDate().toISOString(); } - /** Compares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after. */ + /** + * Compares this date with another. A negative result indicates that this date is before the given + * one, and a positive date indicates that it is after. + */ compare(b: CalendarDate | CalendarDateTime | ZonedDateTime): number { // TODO: Is this a bad idea?? return this.toDate().getTime() - toZoned(b, this.timeZone).toDate().getTime(); diff --git a/packages/@internationalized/date/src/DateFormatter.ts b/packages/@internationalized/date/src/DateFormatter.ts index 06bdcf2b113..ad933014f01 100644 --- a/packages/@internationalized/date/src/DateFormatter.ts +++ b/packages/@internationalized/date/src/DateFormatter.ts @@ -27,7 +27,10 @@ export class DateFormatter implements Intl.DateTimeFormat { this.options = options; } - /** Formats a date as a string according to the locale and format options passed to the constructor. */ + /** + * Formats a date as a string according to the locale and format options passed to the + * constructor. + */ format(value: Date): string { return this.formatter.format(value); } diff --git a/packages/@internationalized/date/src/calendars/GregorianCalendar.ts b/packages/@internationalized/date/src/calendars/GregorianCalendar.ts index 91e5db7f2f9..ff9a6850c19 100644 --- a/packages/@internationalized/date/src/calendars/GregorianCalendar.ts +++ b/packages/@internationalized/date/src/calendars/GregorianCalendar.ts @@ -69,8 +69,9 @@ const daysInMonth = { }; /** - * The Gregorian calendar is the most commonly used calendar system in the world. It supports two eras: BC, and AD. - * Years always contain 12 months, and 365 or 366 days depending on whether it is a leap year. + * The Gregorian calendar is the most commonly used calendar system in the world. It supports two + * eras: BC, and AD. Years always contain 12 months, and 365 or 366 days depending on whether it is + * a leap year. */ export class GregorianCalendar implements Calendar { identifier: CalendarIdentifier = 'gregory'; diff --git a/packages/@internationalized/date/src/calendars/IslamicCalendar.ts b/packages/@internationalized/date/src/calendars/IslamicCalendar.ts index 644e59cd326..d664ff67521 100644 --- a/packages/@internationalized/date/src/calendars/IslamicCalendar.ts +++ b/packages/@internationalized/date/src/calendars/IslamicCalendar.ts @@ -49,11 +49,12 @@ function isLeapYear(year: number): boolean { } /** - * The Islamic calendar, also known as the "Hijri" calendar, is used throughout much of the Arab world. - * The civil variant uses simple arithmetic rules rather than astronomical calculations to approximate - * the traditional calendar, which is based on sighting of the crescent moon. It uses Friday, July 16 622 CE (Julian) as the epoch. - * Each year has 12 months, with either 354 or 355 days depending on whether it is a leap year. - * Learn more about the available Islamic calendars [here](https://cldr.unicode.org/development/development-process/design-proposals/islamic-calendar-types). + * The Islamic calendar, also known as the "Hijri" calendar, is used throughout much of the Arab + * world. The civil variant uses simple arithmetic rules rather than astronomical calculations to + * approximate the traditional calendar, which is based on sighting of the crescent moon. It uses + * Friday, July 16 622 CE (Julian) as the epoch. Each year has 12 months, with either 354 or 355 + * days depending on whether it is a leap year. Learn more about the available Islamic calendars + * [here](https://cldr.unicode.org/development/development-process/design-proposals/islamic-calendar-types). */ export class IslamicCivilCalendar implements Calendar { identifier: CalendarIdentifier = 'islamic-civil'; @@ -102,11 +103,12 @@ export class IslamicCivilCalendar implements Calendar { } /** - * The Islamic calendar, also known as the "Hijri" calendar, is used throughout much of the Arab world. - * The tabular variant uses simple arithmetic rules rather than astronomical calculations to approximate - * the traditional calendar, which is based on sighting of the crescent moon. It uses Thursday, July 15 622 CE (Julian) as the epoch. - * Each year has 12 months, with either 354 or 355 days depending on whether it is a leap year. - * Learn more about the available Islamic calendars [here](https://cldr.unicode.org/development/development-process/design-proposals/islamic-calendar-types). + * The Islamic calendar, also known as the "Hijri" calendar, is used throughout much of the Arab + * world. The tabular variant uses simple arithmetic rules rather than astronomical calculations to + * approximate the traditional calendar, which is based on sighting of the crescent moon. It uses + * Thursday, July 15 622 CE (Julian) as the epoch. Each year has 12 months, with either 354 or 355 + * days depending on whether it is a leap year. Learn more about the available Islamic calendars + * [here](https://cldr.unicode.org/development/development-process/design-proposals/islamic-calendar-types). */ export class IslamicTabularCalendar extends IslamicCivilCalendar { identifier: CalendarIdentifier = 'islamic-tbla'; @@ -156,11 +158,12 @@ function umalquraYearLength(year: number): number { } /** - * The Islamic calendar, also known as the "Hijri" calendar, is used throughout much of the Arab world. - * The Umalqura variant is primarily used in Saudi Arabia. It is a lunar calendar, based on astronomical - * calculations that predict the sighting of a crescent moon. Month and year lengths vary between years - * depending on these calculations. - * Learn more about the available Islamic calendars [here](https://cldr.unicode.org/development/development-process/design-proposals/islamic-calendar-types). + * The Islamic calendar, also known as the "Hijri" calendar, is used throughout much of the Arab + * world. The Umalqura variant is primarily used in Saudi Arabia. It is a lunar calendar, based on + * astronomical calculations that predict the sighting of a crescent moon. Month and year lengths + * vary between years depending on these calculations. Learn more about the available Islamic + * calendars + * [here](https://cldr.unicode.org/development/development-process/design-proposals/islamic-calendar-types). */ export class IslamicUmalquraCalendar extends IslamicCivilCalendar { identifier: CalendarIdentifier = 'islamic-umalqura'; diff --git a/packages/@internationalized/date/src/calendars/JapaneseCalendar.ts b/packages/@internationalized/date/src/calendars/JapaneseCalendar.ts index 52978c98f5c..d1cf7b43a29 100644 --- a/packages/@internationalized/date/src/calendars/JapaneseCalendar.ts +++ b/packages/@internationalized/date/src/calendars/JapaneseCalendar.ts @@ -72,9 +72,10 @@ function toGregorian(date: AnyCalendarDate) { } /** - * The Japanese calendar is based on the Gregorian calendar, but with eras for the reign of each Japanese emperor. - * Whenever a new emperor ascends to the throne, a new era begins and the year starts again from 1. - * Note that eras before 1868 (Gregorian) are not currently supported by this implementation. + * The Japanese calendar is based on the Gregorian calendar, but with eras for the reign of each + * Japanese emperor. Whenever a new emperor ascends to the throne, a new era begins and the year + * starts again from 1. Note that eras before 1868 (Gregorian) are not currently supported by this + * implementation. */ export class JapaneseCalendar extends GregorianCalendar { identifier: CalendarIdentifier = 'japanese'; diff --git a/packages/@internationalized/date/src/conversion.ts b/packages/@internationalized/date/src/conversion.ts index 8a6b72f00cf..bcc18906022 100644 --- a/packages/@internationalized/date/src/conversion.ts +++ b/packages/@internationalized/date/src/conversion.ts @@ -262,7 +262,10 @@ export function fromDateToLocal(date: Date): ZonedDateTime { return fromDate(date, getLocalTimeZone()); } -/** Converts a value with date components such as a `CalendarDateTime` or `ZonedDateTime` into a `CalendarDate`. */ +/** + * Converts a value with date components such as a `CalendarDateTime` or `ZonedDateTime` into a + * `CalendarDate`. + */ export function toCalendarDate(dateTime: AnyCalendarDate): CalendarDate { return new CalendarDate( dateTime.calendar, @@ -292,8 +295,8 @@ export function toTimeFields(date: AnyTime): TimeFields { } /** - * Converts a date value to a `CalendarDateTime`. An optional `Time` value can be passed to set the time - * of the resulting value, otherwise it will default to midnight. + * Converts a date value to a `CalendarDateTime`. An optional `Time` value can be passed to set the + * time of the resulting value, otherwise it will default to midnight. */ export function toCalendarDateTime( date: CalendarDate | CalendarDateTime | ZonedDateTime, @@ -349,8 +352,8 @@ export function toCalendar(date: T, calendar: Calenda } /** - * Converts a date value to a `ZonedDateTime` in the provided time zone. The `disambiguation` option can be set - * to control how values that fall on daylight saving time changes are interpreted. + * Converts a date value to a `ZonedDateTime` in the provided time zone. The `disambiguation` option + * can be set to control how values that fall on daylight saving time changes are interpreted. */ export function toZoned( date: CalendarDate | CalendarDateTime | ZonedDateTime, diff --git a/packages/@internationalized/date/src/queries.ts b/packages/@internationalized/date/src/queries.ts index ee890978a8b..c26cdcbed40 100644 --- a/packages/@internationalized/date/src/queries.ts +++ b/packages/@internationalized/date/src/queries.ts @@ -21,7 +21,10 @@ export function isSameDay(a: DateValue, b: DateValue): boolean { return a.era === b.era && a.year === b.year && a.month === b.month && a.day === b.day; } -/** Returns whether the given dates occur in the same month, using the calendar system of the first date. */ +/** + * Returns whether the given dates occur in the same month, using the calendar system of the first + * date. + */ export function isSameMonth(a: DateValue, b: DateValue): boolean { b = toCalendar(b, a.calendar); // In the Japanese calendar, months can span multiple eras/years, so only compare the first of the month. @@ -30,7 +33,10 @@ export function isSameMonth(a: DateValue, b: DateValue): boolean { return a.era === b.era && a.year === b.year && a.month === b.month; } -/** Returns whether the given dates occur in the same year, using the calendar system of the first date. */ +/** + * Returns whether the given dates occur in the same year, using the calendar system of the first + * date. + */ export function isSameYear(a: DateValue, b: DateValue): boolean { b = toCalendar(b, a.calendar); a = startOfYear(a); diff --git a/packages/@internationalized/date/src/string.ts b/packages/@internationalized/date/src/string.ts index 72b115b336f..c74244586a6 100644 --- a/packages/@internationalized/date/src/string.ts +++ b/packages/@internationalized/date/src/string.ts @@ -102,10 +102,10 @@ export function parseDateTime(value: string): CalendarDateTime { } /** - * Parses an ISO 8601 date and time string with a time zone extension and optional UTC offset - * (e.g. "2021-11-07T00:45[America/Los_Angeles]" or "2021-11-07T00:45-07:00[America/Los_Angeles]"). - * Ambiguous times due to daylight saving time transitions are resolved according to the `disambiguation` - * parameter. + * Parses an ISO 8601 date and time string with a time zone extension and optional UTC offset (e.g. + * "2021-11-07T00:45[America/Los_Angeles]" or "2021-11-07T00:45-07:00[America/Los_Angeles]"). + * Ambiguous times due to daylight saving time transitions are resolved according to the + * `disambiguation` parameter. */ export function parseZonedDateTime(value: string, disambiguation?: Disambiguation): ZonedDateTime { let m = value.match(ZONED_DATE_TIME_RE); @@ -254,6 +254,7 @@ export function zonedDateTimeToString(date: ZonedDateTime): string { /** * Parses an ISO 8601 duration string (e.g. "P3Y6M6W4DT12H30M5S"). + * * @param value An ISO 8601 duration string. * @returns A DateTimeDuration object. */ diff --git a/packages/@internationalized/date/src/types.ts b/packages/@internationalized/date/src/types.ts index f68b25f904b..63e020f75c2 100644 --- a/packages/@internationalized/date/src/types.ts +++ b/packages/@internationalized/date/src/types.ts @@ -61,8 +61,8 @@ export type CalendarIdentifier = */ export interface Calendar { /** - * A string identifier for the calendar, as defined by Unicode CLDR. - * See [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/supportedValuesOf#supported_calendar_types). + * A string identifier for the calendar, as defined by Unicode CLDR. See + * [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/supportedValuesOf#supported_calendar_types). */ identifier: CalendarIdentifier; @@ -141,7 +141,10 @@ export interface TimeDuration { milliseconds?: number; } -/** Represents an amount of time with both date and time components, for use when performing arithmetic. */ +/** + * Represents an amount of time with both date and time components, for use when performing + * arithmetic. + */ export interface DateTimeDuration extends DateDuration, TimeDuration {} export interface DateFields { @@ -173,6 +176,7 @@ export interface CycleTimeOptions extends CycleOptions { * Whether to use 12 or 24 hour time. If 12 hour time is chosen, the resulting value * will remain in the same day period as the original value (e.g. if the value is AM, * the resulting value also be AM). + * * @default 24 */ hourCycle?: 12 | 24; diff --git a/packages/@internationalized/number/src/NumberFormatter.ts b/packages/@internationalized/number/src/NumberFormatter.ts index f045a0d24b9..e1066afe294 100644 --- a/packages/@internationalized/number/src/NumberFormatter.ts +++ b/packages/@internationalized/number/src/NumberFormatter.ts @@ -54,7 +54,8 @@ interface NumberRangeFormatPart extends Intl.NumberFormatPart { } /** - * A wrapper around Intl.NumberFormat providing additional options, polyfills, and caching for performance. + * A wrapper around Intl.NumberFormat providing additional options, polyfills, and caching for + * performance. */ export class NumberFormatter implements Intl.NumberFormat { private numberFormatter: Intl.NumberFormat; @@ -65,7 +66,10 @@ export class NumberFormatter implements Intl.NumberFormat { this.options = options; } - /** Formats a number value as a string, according to the locale and options provided to the constructor. */ + /** + * Formats a number value as a string, according to the locale and options provided to the + * constructor. + */ format(value: number): string { let res = ''; if (!supportsSignDisplay && this.options.signDisplay != null) { @@ -184,7 +188,7 @@ function getCachedNumberFormatter( return numberFormatter; } -/** @private - exported for tests */ +/** @private - Exported for tests */ export function numberFormatSignDisplayPolyfill( numberFormat: Intl.NumberFormat, signDisplay: string, diff --git a/packages/@internationalized/string-compiler/src/stringCompiler.d.ts b/packages/@internationalized/string-compiler/src/stringCompiler.d.ts index c3801f09f17..7ef1b05fa11 100644 --- a/packages/@internationalized/string-compiler/src/stringCompiler.d.ts +++ b/packages/@internationalized/string-compiler/src/stringCompiler.d.ts @@ -13,6 +13,7 @@ interface Options { /** * Output module format. + * * @default 'cjs' */ format?: 'cjs' | 'esm'; diff --git a/packages/@react-aria/i18n/src/useMessageFormatter.ts b/packages/@react-aria/i18n/src/useMessageFormatter.ts index 185ca7832f3..e8f55095d4a 100644 --- a/packages/@react-aria/i18n/src/useMessageFormatter.ts +++ b/packages/@react-aria/i18n/src/useMessageFormatter.ts @@ -30,8 +30,9 @@ function getCachedDictionary(strings: LocalizedStrings) { /** * Handles formatting ICU Message strings to create localized strings for the current locale. * Automatically updates when the locale changes, and handles caching of messages for performance. - * @param strings - A mapping of languages to strings by key. + * * @deprecated - use useLocalizedStringFormatter instead. + * @param strings - A mapping of languages to strings by key. */ export function useMessageFormatter(strings: LocalizedStrings): FormatMessage { let {locale} = useLocale(); diff --git a/packages/@react-aria/test-utils/src/checkboxgroup.ts b/packages/@react-aria/test-utils/src/checkboxgroup.ts index e6d6e47a33b..d36ad75fe10 100644 --- a/packages/@react-aria/test-utils/src/checkboxgroup.ts +++ b/packages/@react-aria/test-utils/src/checkboxgroup.ts @@ -16,7 +16,8 @@ import {pressElement} from './events'; interface TriggerCheckboxOptions { /** - * What interaction type to use when triggering a checkbox. Defaults to the interaction type set on the tester. + * What interaction type to use when triggering a checkbox. Defaults to the interaction type set + * on the tester. */ interactionType?: UserOpts['interactionType']; /** @@ -111,7 +112,8 @@ export class CheckboxGroupTester { } /** - * Toggles the specified checkbox. Defaults to using the interaction type set on the checkbox tester. + * Toggles the specified checkbox. Defaults to using the interaction type set on the checkbox + * tester. */ async toggleCheckbox(opts: TriggerCheckboxOptions): Promise { let {checkbox, interactionType = this._interactionType} = opts; diff --git a/packages/@react-aria/test-utils/src/combobox.ts b/packages/@react-aria/test-utils/src/combobox.ts index 7717d67b3b7..5d67e78e0e2 100644 --- a/packages/@react-aria/test-utils/src/combobox.ts +++ b/packages/@react-aria/test-utils/src/combobox.ts @@ -16,11 +16,13 @@ import {ComboBoxTesterOpts, UserOpts} from './types'; interface ComboBoxOpenOpts { /** * Whether the combobox opens on focus or needs to be manually opened via user action. + * * @default 'manual' */ triggerBehavior?: 'focus' | 'manual'; /** - * What interaction type to use when opening the combobox. Defaults to the interaction type set on the tester. + * What interaction type to use when opening the combobox. Defaults to the interaction type set on + * the tester. */ interactionType?: UserOpts['interactionType']; } @@ -143,8 +145,9 @@ export class ComboBoxTester { } /** - * Selects the desired combobox option. Defaults to using the interaction type set on the combobox tester. If necessary, will open the combobox dropdown beforehand. - * The desired option can be targeted via the option's node, the option's text, or the option's index. + * Selects the desired combobox option. Defaults to using the interaction type set on the combobox + * tester. If necessary, will open the combobox dropdown beforehand. The desired option can be + * targeted via the option's node, the option's text, or the option's index. */ async selectOption(opts: ComboBoxSelectOpts): Promise { let {option, triggerBehavior, interactionType = this._interactionType} = opts; @@ -244,7 +247,8 @@ export class ComboBoxTester { } /** - * Returns the combobox's options if present. Can be filtered to a subsection of the listbox if provided via `element`. + * Returns the combobox's options if present. Can be filtered to a subsection of the listbox if + * provided via `element`. */ options(opts: {element?: HTMLElement} = {}): HTMLElement[] { let {element = this.listbox} = opts; diff --git a/packages/@react-aria/test-utils/src/dialog.ts b/packages/@react-aria/test-utils/src/dialog.ts index 699161810be..3f3795fe4c4 100644 --- a/packages/@react-aria/test-utils/src/dialog.ts +++ b/packages/@react-aria/test-utils/src/dialog.ts @@ -15,7 +15,8 @@ import {DialogTesterOpts, UserOpts} from './types'; interface DialogOpenOpts { /** - * What interaction type to use when opening the dialog. Defaults to the interaction type set on the tester. + * What interaction type to use when opening the dialog. Defaults to the interaction type set on + * the tester. */ interactionType?: UserOpts['interactionType']; } diff --git a/packages/@react-aria/test-utils/src/events.ts b/packages/@react-aria/test-utils/src/events.ts index b37ad6626fd..7631cf5f203 100644 --- a/packages/@react-aria/test-utils/src/events.ts +++ b/packages/@react-aria/test-utils/src/events.ts @@ -48,10 +48,13 @@ export function getMetaKey(): 'MetaLeft' | 'ControlLeft' { /** * Simulates a "long press" event on a element. + * * @param opts - Options for the long press. * @param opts.element - Element to long press. - * @param opts.advanceTimer - Function that when called advances the timers in your test suite by a specific amount of time(ms). - * @param opts.pointeropts - Options to pass to the simulated event. Defaults to mouse. See https://testing-library.com/docs/dom-testing-library/api-events/#fireevent for more info. + * @param opts.advanceTimer - Function that when called advances the timers in your test suite by a + * specific amount of time(ms). + * @param opts.pointeropts - Options to pass to the simulated event. Defaults to mouse. See + * https://testing-library.com/docs/dom-testing-library/api-events/#fireevent for more info. */ export async function triggerLongPress(opts: { element: HTMLElement; diff --git a/packages/@react-aria/test-utils/src/gridlist.ts b/packages/@react-aria/test-utils/src/gridlist.ts index 5f7a9b532f7..1d26138b8cc 100644 --- a/packages/@react-aria/test-utils/src/gridlist.ts +++ b/packages/@react-aria/test-utils/src/gridlist.ts @@ -104,8 +104,9 @@ export class GridListTester { } /** - * Toggles the selection for the specified gridlist row. Defaults to using the interaction type set on the gridlist tester. - * Note that this will endevor to always add/remove JUST the provided row to the set of selected rows. + * Toggles the selection for the specified gridlist row. Defaults to using the interaction type + * set on the gridlist tester. Note that this will endevor to always add/remove JUST the provided + * row to the set of selected rows. */ async toggleRowSelection(opts: GridListToggleRowOpts): Promise { let { @@ -185,7 +186,8 @@ export class GridListTester { // TODO: There is a more difficult use case where the row has/behaves as link, don't think we have a good way to determine that unless the // user specificlly tells us /** - * Triggers the action for the specified gridlist row. Defaults to using the interaction type set on the gridlist tester. + * Triggers the action for the specified gridlist row. Defaults to using the interaction type set + * on the gridlist tester. */ async triggerRowAction(opts: GridListRowActionOpts): Promise { let {row, needsDoubleClick, interactionType = this._interactionType} = opts; @@ -234,7 +236,8 @@ export class GridListTester { } /** - * Returns the gridlist's cells if any. Can be filtered against a specific row if provided via `element`. + * Returns the gridlist's cells if any. Can be filtered against a specific row if provided via + * `element`. */ cells(opts: {element?: HTMLElement} = {}): HTMLElement[] { let {element = this.gridlist} = opts; diff --git a/packages/@react-aria/test-utils/src/listbox.ts b/packages/@react-aria/test-utils/src/listbox.ts index e715fb521b9..12565e2f2d1 100644 --- a/packages/@react-aria/test-utils/src/listbox.ts +++ b/packages/@react-aria/test-utils/src/listbox.ts @@ -16,7 +16,8 @@ import {ListBoxTesterOpts, UserOpts} from './types'; interface ListBoxToggleOptionOpts { /** - * What interaction type to use when toggling selection for an option. Defaults to the interaction type set on the tester. + * What interaction type to use when toggling selection for an option. Defaults to the interaction + * type set on the tester. */ interactionType?: UserOpts['interactionType']; /** @@ -25,18 +26,23 @@ interface ListBoxToggleOptionOpts { option: number | string | HTMLElement; /** * Whether the option should be triggered by Space or Enter in keyboard modality. + * * @default 'Enter' */ keyboardActivation?: 'Space' | 'Enter'; /** - * Whether the option needs to be long pressed to be selected. Depends on the listbox's implementation. + * Whether the option needs to be long pressed to be selected. Depends on the listbox's + * implementation. */ needsLongPress?: boolean; /** - * Whether the listbox has a selectionBehavior of "toggle" or "replace" (aka highlight selection). This affects the user operations - * required to toggle option selection by adding modifier keys during user actions, useful when performing multi-option selection in a "selectionBehavior: 'replace'" listbox. - * If you would like to still simulate user actions (aka press) without these modifiers keys for a "selectionBehavior: replace" listbox, simply omit this option. - * See the [RAC Listbox docs](https://react-spectrum.adobe.com/react-aria/ListBox.html#selection-behavior) for more info on this behavior. + * Whether the listbox has a selectionBehavior of "toggle" or "replace" (aka highlight selection). + * This affects the user operations required to toggle option selection by adding modifier keys + * during user actions, useful when performing multi-option selection in a "selectionBehavior: + * 'replace'" listbox. If you would like to still simulate user actions (aka press) without these + * modifiers keys for a "selectionBehavior: replace" listbox, simply omit this option. See the + * [RAC Listbox docs](https://react-spectrum.adobe.com/react-aria/ListBox.html#selection-behavior) + * for more info on this behavior. * * @default 'toggle' */ @@ -48,7 +54,8 @@ interface ListBoxOptionActionOpts extends Omit< 'keyboardActivation' | 'needsLongPress' > { /** - * Whether or not the option needs a double click to trigger the option action. Depends on the listbox's implementation. + * Whether or not the option needs a double click to trigger the option action. Depends on the + * listbox's implementation. */ needsDoubleClick?: boolean; } @@ -137,7 +144,8 @@ export class ListBoxTester { } /** - * Toggles the selection for the specified listbox option. Defaults to using the interaction type set on the listbox tester. + * Toggles the selection for the specified listbox option. Defaults to using the interaction type + * set on the listbox tester. */ async toggleOptionSelection(opts: ListBoxToggleOptionOpts): Promise { let { @@ -199,7 +207,8 @@ export class ListBoxTester { } /** - * Triggers the action for the specified listbox option. Defaults to using the interaction type set on the listbox tester. + * Triggers the action for the specified listbox option. Defaults to using the interaction type + * set on the listbox tester. */ async triggerOptionAction(opts: ListBoxOptionActionOpts): Promise { let {option, needsDoubleClick, interactionType = this._interactionType} = opts; @@ -234,7 +243,8 @@ export class ListBoxTester { } /** - * Returns the listbox options. Can be filtered to a subsection of the listbox if provided via `element`. + * Returns the listbox options. Can be filtered to a subsection of the listbox if provided via + * `element`. */ options(opts: {element?: HTMLElement} = {}): HTMLElement[] { let {element = this._listbox} = opts; diff --git a/packages/@react-aria/test-utils/src/menu.ts b/packages/@react-aria/test-utils/src/menu.ts index ae18008590a..940c4412fe9 100644 --- a/packages/@react-aria/test-utils/src/menu.ts +++ b/packages/@react-aria/test-utils/src/menu.ts @@ -20,7 +20,8 @@ interface MenuOpenOpts { */ needsLongPress?: boolean; /** - * What interaction type to use when opening the menu. Defaults to the interaction type set on the tester. + * What interaction type to use when opening the menu. Defaults to the interaction type set on the + * tester. */ interactionType?: UserOpts['interactionType']; /** @@ -35,17 +36,21 @@ interface MenuSelectOpts extends MenuOpenOpts { */ option: number | string | HTMLElement; /** - * The menu's selection mode. Will affect whether or not the menu is expected to be closed upon option selection. + * The menu's selection mode. Will affect whether or not the menu is expected to be closed upon + * option selection. + * * @default 'single' */ menuSelectionMode?: 'single' | 'multiple'; /** * Whether or not the menu closes on select. Depends on menu implementation and configuration. + * * @default true */ closesOnSelect?: boolean; /** * Whether the option should be triggered by Space or Enter in keyboard modality. + * * @default 'Enter' */ keyboardActivation?: 'Space' | 'Enter'; @@ -53,7 +58,8 @@ interface MenuSelectOpts extends MenuOpenOpts { interface MenuOpenSubmenuOpts extends MenuOpenOpts { /** - * The text or node of the submenu trigger to open. Available submenu trigger nodes can be sourced via `submenuTriggers`. + * The text or node of the submenu trigger to open. Available submenu trigger nodes can be sourced + * via `submenuTriggers`. */ submenuTrigger: string | HTMLElement; } @@ -177,8 +183,9 @@ export class MenuTester { // TODO: also very similar to select, barring potential long press support // Close on select is also kinda specific? /** - * Selects the desired menu option. Defaults to using the interaction type set on the menu tester. If necessary, will open the menu dropdown beforehand. - * The desired option can be targeted via the option's node, the option's text, or the option's index. + * Selects the desired menu option. Defaults to using the interaction type set on the menu tester. + * If necessary, will open the menu dropdown beforehand. The desired option can be targeted via + * the option's node, the option's text, or the option's index. */ async selectOption(opts: MenuSelectOpts): Promise { let { @@ -300,7 +307,8 @@ export class MenuTester { // TODO: update this to remove needsLongPress if we wanna make the user call open first always /** - * Opens the submenu. Defaults to using the interaction type set on the menu tester. The submenu trigger can be targeted via the trigger's node or the trigger's text. + * Opens the submenu. Defaults to using the interaction type set on the menu tester. The submenu + * trigger can be targeted via the trigger's node or the trigger's text. */ async openSubmenu(opts: MenuOpenSubmenuOpts): Promise { let {submenuTrigger, needsLongPress, interactionType = this._interactionType} = opts; @@ -432,7 +440,8 @@ export class MenuTester { } /** - * Returns the menu's options if present. Can be filtered to a subsection of the menu if provided via `element`. + * Returns the menu's options if present. Can be filtered to a subsection of the menu if provided + * via `element`. */ options(opts: {element?: HTMLElement} = {}): HTMLElement[] { let {element = this.menu} = opts; diff --git a/packages/@react-aria/test-utils/src/radiogroup.ts b/packages/@react-aria/test-utils/src/radiogroup.ts index 36cf189b09e..deec38e3533 100644 --- a/packages/@react-aria/test-utils/src/radiogroup.ts +++ b/packages/@react-aria/test-utils/src/radiogroup.ts @@ -16,7 +16,8 @@ import {pressElement} from './events'; interface TriggerRadioOptions { /** - * What interaction type to use when triggering a radio. Defaults to the interaction type set on the tester. + * What interaction type to use when triggering a radio. Defaults to the interaction type set on + * the tester. */ interactionType?: UserOpts['interactionType']; /** diff --git a/packages/@react-aria/test-utils/src/select.ts b/packages/@react-aria/test-utils/src/select.ts index c164afd04fd..1dadfd77dbf 100644 --- a/packages/@react-aria/test-utils/src/select.ts +++ b/packages/@react-aria/test-utils/src/select.ts @@ -15,7 +15,8 @@ import {SelectTesterOpts, UserOpts} from './types'; interface SelectOpenOpts { /** - * What interaction type to use when opening the select. Defaults to the interaction type set on the tester. + * What interaction type to use when opening the select. Defaults to the interaction type set on + * the tester. */ interactionType?: UserOpts['interactionType']; } @@ -26,7 +27,9 @@ interface SelectTriggerOptionOpts extends SelectOpenOpts { */ option: number | string | HTMLElement; /** - * Whether or not the select closes on selection. Depends on select implementation and configuration. + * Whether or not the select closes on selection. Depends on select implementation and + * configuration. + * * @default true */ closesOnSelect?: boolean; @@ -165,8 +168,9 @@ export class SelectTester { } /** - * Selects the desired select option. Defaults to using the interaction type set on the select tester. If necessary, will open the select dropdown beforehand. - * The desired option can be targeted via the option's node, the option's text, or the option's index. + * Selects the desired select option. Defaults to using the interaction type set on the select + * tester. If necessary, will open the select dropdown beforehand. The desired option can be + * targeted via the option's node, the option's text, or the option's index. */ async selectOption(opts: SelectTriggerOptionOpts): Promise { let {option, closesOnSelect, interactionType = this._interactionType} = opts || {}; @@ -232,7 +236,8 @@ export class SelectTester { } /** - * Returns the select's options if present. Can be filtered to a subsection of the listbox if provided via `element`. + * Returns the select's options if present. Can be filtered to a subsection of the listbox if + * provided via `element`. */ options(opts: {element?: HTMLElement} = {}): HTMLElement[] { let {element = this.listbox} = opts; diff --git a/packages/@react-aria/test-utils/src/table.ts b/packages/@react-aria/test-utils/src/table.ts index ffdefecbba6..2541dbeb6c5 100644 --- a/packages/@react-aria/test-utils/src/table.ts +++ b/packages/@react-aria/test-utils/src/table.ts @@ -28,7 +28,8 @@ interface TableToggleSortOpts { */ column: number | string | HTMLElement; /** - * What interaction type to use when sorting the column. Defaults to the interaction type set on the tester. + * What interaction type to use when sorting the column. Defaults to the interaction type set on + * the tester. */ interactionType?: UserOpts['interactionType']; } @@ -117,7 +118,8 @@ export class TableTester { } /** - * Toggles the selection for the specified table row. Defaults to using the interaction type set on the table tester. + * Toggles the selection for the specified table row. Defaults to using the interaction type set + * on the table tester. */ async toggleRowSelection(opts: TableToggleRowOpts): Promise { let { @@ -183,7 +185,8 @@ export class TableTester { } /** - * Toggles the expansion for the specified tree row. Defaults to using the interaction type set on the tree tester. + * Toggles the expansion for the specified tree row. Defaults to using the interaction type set on + * the tree tester. */ async toggleRowExpansion(opts: TableToggleExpansionOpts): Promise { let {row, interactionType = this._interactionType} = opts; @@ -224,7 +227,8 @@ export class TableTester { } /** - * Toggles the sort order for the specified table column. Defaults to using the interaction type set on the table tester. + * Toggles the sort order for the specified table column. Defaults to using the interaction type + * set on the table tester. */ async toggleSort(opts: TableToggleSortOpts): Promise { let {column, interactionType = this._interactionType} = opts; @@ -323,7 +327,8 @@ export class TableTester { } /** - * Triggers an action for the specified table column menu. Defaults to using the interaction type set on the table tester. + * Triggers an action for the specified table column menu. Defaults to using the interaction type + * set on the table tester. */ async triggerColumnHeaderAction(opts: TableColumnHeaderActionOpts): Promise { let {column, interactionType = this._interactionType, action} = opts; @@ -413,7 +418,8 @@ export class TableTester { } /** - * Triggers the action for the specified table row. Defaults to using the interaction type set on the table tester. + * Triggers the action for the specified table row. Defaults to using the interaction type set on + * the table tester. */ async triggerRowAction(opts: TableRowActionOpts): Promise { let {row, needsDoubleClick, interactionType = this._interactionType} = opts; @@ -442,7 +448,8 @@ export class TableTester { // Additionally, should we also support keyboard navigation/typeahead? Those felt like they could be very easily replicated by the user via user.keyboard already and don't really // add much value if we provide that to them /** - * Toggle selection for all rows in the table. Defaults to using the interaction type set on the table tester. + * Toggle selection for all rows in the table. Defaults to using the interaction type set on the + * table tester. */ async toggleSelectAll(opts: {interactionType?: UserOpts['interactionType']} = {}): Promise { let {interactionType = this._interactionType} = opts; @@ -541,7 +548,8 @@ export class TableTester { } /** - * Returns the cells within the table if any. Can be filtered against a specific row if provided via `element`. + * Returns the cells within the table if any. Can be filtered against a specific row if provided + * via `element`. */ cells(opts: {element?: HTMLElement} = {}): HTMLElement[] { let {element = this.table} = opts; diff --git a/packages/@react-aria/test-utils/src/tabs.ts b/packages/@react-aria/test-utils/src/tabs.ts index 1f2b4e6a571..d58ae129cc8 100644 --- a/packages/@react-aria/test-utils/src/tabs.ts +++ b/packages/@react-aria/test-utils/src/tabs.ts @@ -16,7 +16,8 @@ import {pressElement} from './events'; interface TriggerTabOptions { /** - * What interaction type to use when triggering a tab. Defaults to the interaction type set on the tester. + * What interaction type to use when triggering a tab. Defaults to the interaction type set on the + * tester. */ interactionType?: UserOpts['interactionType']; /** diff --git a/packages/@react-aria/test-utils/src/tree.ts b/packages/@react-aria/test-utils/src/tree.ts index 3be1ef079ad..9cd06f73e9a 100644 --- a/packages/@react-aria/test-utils/src/tree.ts +++ b/packages/@react-aria/test-utils/src/tree.ts @@ -114,8 +114,9 @@ export class TreeTester { } /** - * Toggles the selection for the specified tree row. Defaults to using the interaction type set on the tree tester. - * Note that this will endevor to always add/remove JUST the provided row to the set of selected rows. + * Toggles the selection for the specified tree row. Defaults to using the interaction type set on + * the tree tester. Note that this will endevor to always add/remove JUST the provided row to the + * set of selected rows. */ async toggleRowSelection(opts: TreeToggleRowOpts): Promise { let { @@ -194,7 +195,8 @@ export class TreeTester { } /** - * Toggles the expansion for the specified tree row. Defaults to using the interaction type set on the tree tester. + * Toggles the expansion for the specified tree row. Defaults to using the interaction type set on + * the tree tester. */ async toggleRowExpansion(opts: TreeToggleExpansionOpts): Promise { let {row, interactionType = this._interactionType} = opts; @@ -235,7 +237,8 @@ export class TreeTester { } /** - * Triggers the action for the specified tree row. Defaults to using the interaction type set on the tree tester. + * Triggers the action for the specified tree row. Defaults to using the interaction type set on + * the tree tester. */ async triggerRowAction(opts: TreeRowActionOpts): Promise { let {row, needsDoubleClick, interactionType = this._interactionType} = opts; @@ -286,7 +289,8 @@ export class TreeTester { } /** - * Returns the tree's cells if any. Can be filtered against a specific row if provided via `element`. + * Returns the tree's cells if any. Can be filtered against a specific row if provided via + * `element`. */ cells(opts: {element?: HTMLElement} = {}): HTMLElement[] { let {element = this.tree} = opts; diff --git a/packages/@react-aria/test-utils/src/types.ts b/packages/@react-aria/test-utils/src/types.ts index 6944aa8c931..727316debee 100644 --- a/packages/@react-aria/test-utils/src/types.ts +++ b/packages/@react-aria/test-utils/src/types.ts @@ -17,8 +17,9 @@ export type Direction = 'ltr' | 'rtl'; // curent way is like https://testing-library.com/docs/user-event/options/#advancetimers, export interface UserOpts { /** - * The interaction type (mouse, touch, keyboard) that the test util user will use when interacting with a component. This can be overridden - * at the aria pattern tester level if needed. + * The interaction type (mouse, touch, keyboard) that the test util user will use when interacting + * with a component. This can be overridden at the aria pattern tester level if needed. + * * @default mouse */ interactionType?: 'mouse' | 'touch' | 'keyboard'; @@ -26,8 +27,8 @@ export interface UserOpts { // A real timer user would pass (waitTime) => new Promise((resolve) => setTimeout(resolve, waitTime)) // Time is in ms. /** - * A function used by the test utils to advance timers during interactions. Required for certain aria patterns (e.g. table). This can be overridden - * at the aria pattern tester level if needed. + * A function used by the test utils to advance timers during interactions. Required for certain + * aria patterns (e.g. table). This can be overridden at the aria pattern tester level if needed. */ advanceTimer?: (time: number) => unknown | Promise; } @@ -43,13 +44,14 @@ export interface CheckboxGroupTesterOpts extends BaseTesterOpts {} export interface ComboBoxTesterOpts extends BaseTesterOpts { /** - * The base element for the combobox. If provided the wrapping element around the target combobox (as is the the case with a ref provided to RSP ComboBox), - * will automatically search for the combobox element within. + * The base element for the combobox. If provided the wrapping element around the target combobox + * (as is the the case with a ref provided to RSP ComboBox), will automatically search for the + * combobox element within. */ root: HTMLElement; /** - * The node of the combobox trigger button if any. If not provided, we will try to automatically use any button - * within the `root` provided or that the `root` serves as the trigger. + * The node of the combobox trigger button if any. If not provided, we will try to automatically + * use any button within the `root` provided or that the `root` serves as the trigger. */ trigger?: HTMLElement; } @@ -92,6 +94,7 @@ export interface MenuTesterOpts extends BaseTesterOpts { export interface RadioGroupTesterOpts extends BaseTesterOpts { /** * The horizontal layout direction, typically affected by locale. + * * @default 'ltr' */ direction?: Direction; @@ -99,8 +102,9 @@ export interface RadioGroupTesterOpts extends BaseTesterOpts { export interface SelectTesterOpts extends BaseTesterOpts { /** - * The trigger element for the select. If provided the wrapping element around the target select (as is the case with a ref provided to RSP Select), - * will automatically search for the select's trigger element within. + * The trigger element for the select. If provided the wrapping element around the target select + * (as is the case with a ref provided to RSP Select), will automatically search for the select's + * trigger element within. */ root: HTMLElement; } @@ -115,6 +119,7 @@ export interface TableTesterOpts extends BaseTesterOpts { export interface TabsTesterOpts extends BaseTesterOpts { /** * The horizontal layout direction, typically affected by locale. + * * @default 'ltr' */ direction?: Direction; @@ -133,27 +138,34 @@ export interface BaseGridRowInteractionOpts { */ row: number | string | HTMLElement; /** - * What interaction type to use when interacting with the row. Defaults to the interaction type set on the tester. + * What interaction type to use when interacting with the row. Defaults to the interaction type + * set on the tester. */ interactionType?: UserOpts['interactionType']; } export interface ToggleGridRowOpts extends BaseGridRowInteractionOpts { /** - * Whether the row needs to be long pressed to be selected. Depends on the components implementation. + * Whether the row needs to be long pressed to be selected. Depends on the components + * implementation. */ needsLongPress?: boolean; /** - * Whether the checkbox should be used to select the row. If false, will attempt to select the row via press. + * Whether the checkbox should be used to select the row. If false, will attempt to select the row + * via press. + * * @default 'true' */ checkboxSelection?: boolean; // TODO: this api feels a bit confusing tbh... /** - * Whether the grid has a selectionBehavior of "toggle" or "replace" (aka highlight selection). This affects the user operations - * required to toggle row selection by adding modifier keys during user actions, useful when performing multi-row selection in a "selectionBehavior: 'replace'" grid. - * If you would like to still simulate user actions (aka press) without these modifiers keys for a "selectionBehavior: replace" grid, simply omit this option. - * See the "Selection Behavior" section of the appropriate React Aria Component docs for more information (e.g. https://react-spectrum.adobe.com/react-aria/Tree.html#selection-behavior). + * Whether the grid has a selectionBehavior of "toggle" or "replace" (aka highlight selection). + * This affects the user operations required to toggle row selection by adding modifier keys + * during user actions, useful when performing multi-row selection in a "selectionBehavior: + * 'replace'" grid. If you would like to still simulate user actions (aka press) without these + * modifiers keys for a "selectionBehavior: replace" grid, simply omit this option. See the + * "Selection Behavior" section of the appropriate React Aria Component docs for more information + * (e.g. https://react-spectrum.adobe.com/react-aria/Tree.html#selection-behavior). * * @default 'toggle' */ @@ -162,7 +174,8 @@ export interface ToggleGridRowOpts extends BaseGridRowInteractionOpts { export interface GridRowActionOpts extends BaseGridRowInteractionOpts { /** - * Whether or not the row needs a double click to trigger the row action. Depends on the components implementation. + * Whether or not the row needs a double click to trigger the row action. Depends on the + * components implementation. */ needsDoubleClick?: boolean; } diff --git a/packages/@react-aria/test-utils/src/user.ts b/packages/@react-aria/test-utils/src/user.ts index 944cc117a2d..27131200cb9 100644 --- a/packages/@react-aria/test-utils/src/user.ts +++ b/packages/@react-aria/test-utils/src/user.ts @@ -120,13 +120,15 @@ let defaultAdvanceTimer = (waitTime: number | undefined) => export class User { private user; /** - * The interaction type (mouse, touch, keyboard) that the test util user will use when interacting with a component. This can be overridden - * at the aria pattern util level if needed. + * The interaction type (mouse, touch, keyboard) that the test util user will use when interacting + * with a component. This can be overridden at the aria pattern util level if needed. + * * @default mouse */ interactionType: UserOpts['interactionType']; /** - * A function used by the test utils to advance timers during interactions. Required for certain aria patterns (e.g. table). + * A function used by the test utils to advance timers during interactions. Required for certain + * aria patterns (e.g. table). */ advanceTimer: UserOpts['advanceTimer']; diff --git a/packages/@react-spectrum/s2/src/Accordion.tsx b/packages/@react-spectrum/s2/src/Accordion.tsx index 91f8b18b5bc..807780cc486 100644 --- a/packages/@react-spectrum/s2/src/Accordion.tsx +++ b/packages/@react-spectrum/s2/src/Accordion.tsx @@ -39,11 +39,13 @@ export interface AccordionProps extends UnsafeStyles, DOMProps, SlotProps { styles?: StylesPropWithHeight; /** * The size of the accordion. + * * @default 'M' */ size?: 'S' | 'M' | 'L' | 'XL'; /** * The amount of space between the accordion items. + * * @default 'regular' */ density?: 'compact' | 'regular' | 'spacious'; @@ -111,16 +113,19 @@ export interface AccordionItemState { export interface AccordionItemRenderProps { /** * Whether the accordion item is expanded. + * * @selector [data-expanded] */ isExpanded: boolean; /** * Whether the accordion item has keyboard focus. + * * @selector [data-focus-visible-within] */ isFocusVisibleWithin: boolean; /** * Whether the accordion item is disabled. + * * @selector [data-disabled] */ isDisabled: boolean; @@ -137,17 +142,22 @@ export interface AccordionItemProps StyleProps { /** * The size of the accordion item. + * * @default 'M' */ size?: 'S' | 'M' | 'L' | 'XL'; /** * The amount of space between the accordion item. + * * @default 'regular' */ density?: 'compact' | 'regular' | 'spacious'; /** Whether the accordion item should be displayed with a quiet style. */ isQuiet?: boolean; - /** The contents of the accordion item, consisting of a accordion item title and accordion item panel. */ + /** + * The contents of the accordion item, consisting of a accordion item title and accordion item + * panel. + */ children: ReactNode; /** An id for the accordion item, matching the id used in `expandedKeys`. */ id?: Key; @@ -162,7 +172,8 @@ export interface AccordionItemProps } /** - * A accordion item is a collapsible section of content. It is composed of a header with a heading and trigger button, and a panel that contains the content. + * A accordion item is a collapsible section of content. It is composed of a header with a heading + * and trigger button, and a panel that contains the content. */ export const AccordionItem = forwardRef(function AccordionItem( props: AccordionItemProps, @@ -172,7 +183,8 @@ export const AccordionItem = forwardRef(function AccordionItem( }); export interface AccordionItemTitleProps extends UnsafeStyles, DOMProps { - /** The heading level of the accordion item title. + /** + * The heading level of the accordion item title. * * @default 3 */ @@ -182,7 +194,8 @@ export interface AccordionItemTitleProps extends UnsafeStyles, DOMProps { } /** - * An accordion item title consisting of a heading and a trigger button to expand/collapse the panel. + * An accordion item title consisting of a heading and a trigger button to expand/collapse the + * panel. */ export const AccordionItemTitle = forwardRef(function AccordionItemTitle( props: AccordionItemTitleProps, @@ -197,7 +210,8 @@ export interface AccordionItemHeaderProps extends UnsafeStyles, DOMProps { } /** - * A wrapper element for the accordion item title that can contain other elements not part of the trigger. + * A wrapper element for the accordion item title that can contain other elements not part of the + * trigger. */ export const AccordionItemHeader = forwardRef(function AccordionItemHeader( props: AccordionItemHeaderProps, @@ -211,13 +225,15 @@ export interface AccordionItemPanelProps extends UnsafeStyles, DOMProps, AriaLab children: React.ReactNode; /** * The accessibility role for the accordion item panel. + * * @default 'group' */ role?: 'group' | 'region'; } /** - * An accordion item panel is a collapsible section of content that is hidden until the accordion item is expanded. + * An accordion item panel is a collapsible section of content that is hidden until the accordion + * item is expanded. */ export const AccordionItemPanel = forwardRef(function AccordionItemPanel( props: AccordionItemPanelProps, diff --git a/packages/@react-spectrum/s2/src/ActionBar.tsx b/packages/@react-spectrum/s2/src/ActionBar.tsx index f6d6c3a637d..a108a1644ab 100644 --- a/packages/@react-spectrum/s2/src/ActionBar.tsx +++ b/packages/@react-spectrum/s2/src/ActionBar.tsx @@ -95,7 +95,10 @@ export interface ActionBarProps extends SlotProps, StyleProps, DOMProps { children: ReactNode; /** Whether the ActionBar should be displayed with a emphasized style. */ isEmphasized?: boolean; - /** The number of selected items that the ActionBar is currently linked to. If 0, the ActionBar is hidden. */ + /** + * The number of selected items that the ActionBar is currently linked to. If 0, the ActionBar is + * hidden. + */ selectedItemCount?: number | 'all'; /** Handler that is called when the ActionBar clear button is pressed. */ onClearSelection?: () => void; @@ -107,7 +110,8 @@ export const ActionBarContext = createContext, DOMRefValue>>(null); /** - * Action bars are used for single and bulk selection patterns when a user needs to perform actions on one or more items at the same time. + * Action bars are used for single and bulk selection patterns when a user needs to perform actions + * on one or more items at the same time. */ export const ActionBar = forwardRef(function ActionBar( props: ActionBarProps, diff --git a/packages/@react-spectrum/s2/src/ActionButton.tsx b/packages/@react-spectrum/s2/src/ActionButton.tsx index a7ce10bea12..0f5b6245add 100644 --- a/packages/@react-spectrum/s2/src/ActionButton.tsx +++ b/packages/@react-spectrum/s2/src/ActionButton.tsx @@ -49,14 +49,20 @@ export interface ActionButtonStyleProps { size?: 'XS' | 'S' | 'M' | 'L' | 'XL'; /** The static color style to apply. Useful when the ActionButton appears over a color background. */ staticColor?: 'black' | 'white' | 'auto'; - /** Whether the button should be displayed with a [quiet style](https://spectrum.adobe.com/page/action-button/#Quiet). */ + /** + * Whether the button should be displayed with a [quiet + * style](https://spectrum.adobe.com/page/action-button/#Quiet). + */ isQuiet?: boolean; } interface ToggleButtonStyleProps { /** Whether the ActionButton should be selected (controlled). */ isSelected?: boolean; - /** Whether the button should be displayed with an [emphasized style](https://spectrum.adobe.com/page/action-button/#Emphasis). */ + /** + * Whether the button should be displayed with an [emphasized + * style](https://spectrum.adobe.com/page/action-button/#Emphasis). + */ isEmphasized?: boolean; } @@ -307,8 +313,9 @@ export const ActionButtonContext = ); /** - * ActionButtons allow users to perform an action. - * They're used for similar, task-based options within a workflow, and are ideal for interfaces where buttons aren't meant to draw a lot of attention. + * ActionButtons allow users to perform an action. They're used for similar, task-based options + * within a workflow, and are ideal for interfaces where buttons aren't meant to draw a lot of + * attention. */ export const ActionButton = forwardRef(function ActionButton( props: ActionButtonProps, diff --git a/packages/@react-spectrum/s2/src/ActionButtonGroup.tsx b/packages/@react-spectrum/s2/src/ActionButtonGroup.tsx index 908bd18a052..7530098a6d5 100644 --- a/packages/@react-spectrum/s2/src/ActionButtonGroup.tsx +++ b/packages/@react-spectrum/s2/src/ActionButtonGroup.tsx @@ -29,22 +29,31 @@ export interface ActionButtonGroupProps extends AriaLabelingProps, UnsafeStyles, children: ReactNode; /** * Size of the buttons. - * @default "M" + * + * @default 'M' */ size?: 'XS' | 'S' | 'M' | 'L' | 'XL'; /** * Spacing between the buttons. - * @default "regular" + * + * @default 'regular' */ density?: 'compact' | 'regular'; - /** Whether the button should be displayed with a [quiet style](https://spectrum.adobe.com/page/action-button/#Quiet). */ + /** + * Whether the button should be displayed with a [quiet + * style](https://spectrum.adobe.com/page/action-button/#Quiet). + */ isQuiet?: boolean; /** Whether the buttons should divide the container width equally. */ isJustified?: boolean; - /** The static color style to apply. Useful when the ActionButtonGroup appears over a color background. */ + /** + * The static color style to apply. Useful when the ActionButtonGroup appears over a color + * background. + */ staticColor?: 'white' | 'black' | 'auto'; /** * The axis the group should align with. + * * @default 'horizontal' */ orientation?: 'horizontal' | 'vertical'; diff --git a/packages/@react-spectrum/s2/src/AlertDialog.tsx b/packages/@react-spectrum/s2/src/AlertDialog.tsx index 94237308ae4..32312004334 100644 --- a/packages/@react-spectrum/s2/src/AlertDialog.tsx +++ b/packages/@react-spectrum/s2/src/AlertDialog.tsx @@ -31,6 +31,7 @@ import {useLocalizedStringFormatter} from 'react-aria/useLocalizedStringFormatte export interface AlertDialogProps extends DOMProps, UnsafeStyles { /** * The [visual style](https://spectrum.adobe.com/page/alert-dialog/#Options) of the AlertDialog. + * * @default 'confirmation' */ variant?: 'confirmation' | 'information' | 'destructive' | 'error' | 'warning'; @@ -78,7 +79,8 @@ const icon = style({ }); /** - * AlertDialogs are a specific type of Dialog. They display important information that users need to acknowledge. + * AlertDialogs are a specific type of Dialog. They display important information that users need to + * acknowledge. */ export const AlertDialog = forwardRef(function AlertDialog(props: AlertDialogProps, ref: DOMRef) { let stringFormatter = useLocalizedStringFormatter(intlMessages, '@react-spectrum/s2'); diff --git a/packages/@react-spectrum/s2/src/Avatar.tsx b/packages/@react-spectrum/s2/src/Avatar.tsx index 5a136da38d4..20c8347a5ba 100644 --- a/packages/@react-spectrum/s2/src/Avatar.tsx +++ b/packages/@react-spectrum/s2/src/Avatar.tsx @@ -35,6 +35,7 @@ export interface AvatarProps extends UnsafeStyles, DOMProps, SlotProps { styles?: StylesPropWithoutWidth; /** * The size of the avatar. + * * @default 24 */ size?: 16 | 20 | 24 | 28 | 32 | 36 | 40 | 44 | 48 | 56 | 64 | 80 | 96 | 112 | (number & {}); diff --git a/packages/@react-spectrum/s2/src/AvatarGroup.tsx b/packages/@react-spectrum/s2/src/AvatarGroup.tsx index 7c2dcc094d9..89a896daa21 100644 --- a/packages/@react-spectrum/s2/src/AvatarGroup.tsx +++ b/packages/@react-spectrum/s2/src/AvatarGroup.tsx @@ -32,6 +32,7 @@ export interface AvatarGroupProps extends UnsafeStyles, DOMProps, AriaLabelingPr label?: string; /** * The size of the avatar group. + * * @default 24 */ size?: 16 | 20 | 24 | 28 | 32 | 36 | 40; diff --git a/packages/@react-spectrum/s2/src/Badge.tsx b/packages/@react-spectrum/s2/src/Badge.tsx index 034de44856c..9bdb65e0b14 100644 --- a/packages/@react-spectrum/s2/src/Badge.tsx +++ b/packages/@react-spectrum/s2/src/Badge.tsx @@ -32,7 +32,8 @@ export interface BadgeStyleProps { */ size?: 'S' | 'M' | 'L' | 'XL'; /** - * The variant changes the background color of the badge. When badge has a semantic meaning, they should use the variant for semantic colors. + * The variant changes the background color of the badge. When badge has a semantic meaning, they + * should use the variant for semantic colors. * * @default 'neutral' */ @@ -64,11 +65,13 @@ export interface BadgeStyleProps { | 'silver'; /** * The fill of the badge. + * * @default 'bold' */ fillStyle?: 'bold' | 'subtle' | 'outline'; /** * Sets the text behavior for the contents. + * * @default 'wrap' */ overflowMode?: 'wrap' | 'truncate'; @@ -194,7 +197,8 @@ const badge = style( ); /** - * Badges are used for showing a small amount of color-categorized metadata, ideal for getting a user's attention. + * Badges are used for showing a small amount of color-categorized metadata, ideal for getting a + * user's attention. */ export const Badge = forwardRef(function Badge(props: BadgeProps, ref: DOMRef) { [props, ref] = useSpectrumContextProps(props, ref, BadgeContext); diff --git a/packages/@react-spectrum/s2/src/Button.tsx b/packages/@react-spectrum/s2/src/Button.tsx index 6293aa3a9ab..d841ea51c27 100644 --- a/packages/@react-spectrum/s2/src/Button.tsx +++ b/packages/@react-spectrum/s2/src/Button.tsx @@ -515,7 +515,8 @@ export const Button = forwardRef(function Button( }); /** - * A LinkButton combines the functionality of a link with the appearance of a button. Useful for allowing users to navigate to another page. + * A LinkButton combines the functionality of a link with the appearance of a button. Useful for + * allowing users to navigate to another page. */ export const LinkButton = forwardRef(function LinkButton( props: LinkButtonProps, diff --git a/packages/@react-spectrum/s2/src/Calendar.tsx b/packages/@react-spectrum/s2/src/Calendar.tsx index cd68c0f3383..9e90445a261 100644 --- a/packages/@react-spectrum/s2/src/Calendar.tsx +++ b/packages/@react-spectrum/s2/src/Calendar.tsx @@ -81,6 +81,7 @@ export interface CalendarProps ReactNode); /** * The size of the Card. + * * @default 'M' */ size?: 'XS' | 'S' | 'M' | 'L' | 'XL'; /** * The amount of internal padding within the Card. + * * @default 'regular' */ density?: 'compact' | 'regular' | 'spacious'; /** * The visual style of the Card. + * * @default 'primary' */ variant?: 'primary' | 'secondary' | 'tertiary' | 'quiet'; diff --git a/packages/@react-spectrum/s2/src/CardView.tsx b/packages/@react-spectrum/s2/src/CardView.tsx index 161a4c55d86..6579fb4a224 100644 --- a/packages/@react-spectrum/s2/src/CardView.tsx +++ b/packages/@react-spectrum/s2/src/CardView.tsx @@ -69,26 +69,31 @@ export interface CardViewProps UnsafeStyles { /** * The layout of the cards. + * * @default 'grid' */ layout?: 'grid' | 'waterfall'; /** * The size of the cards. + * * @default 'M' */ size?: 'XS' | 'S' | 'M' | 'L' | 'XL'; /** * The amount of space between the cards. + * * @default 'regular' */ density?: 'compact' | 'regular' | 'spacious'; /** * The visual style of the cards. + * * @default 'primary' */ variant?: 'primary' | 'secondary' | 'tertiary' | 'quiet'; /** * How selection should be displayed. + * * @default 'checkbox' */ selectionStyle?: 'checkbox' | 'highlight'; diff --git a/packages/@react-spectrum/s2/src/CoachMark.tsx b/packages/@react-spectrum/s2/src/CoachMark.tsx index 0edc12d9e18..b6137f81286 100644 --- a/packages/@react-spectrum/s2/src/CoachMark.tsx +++ b/packages/@react-spectrum/s2/src/CoachMark.tsx @@ -385,9 +385,9 @@ export const CoachMark = forwardRef((props: CoachMarkProps, ref: ForwardedRef(null); diff --git a/packages/@react-spectrum/s2/src/ColorArea.tsx b/packages/@react-spectrum/s2/src/ColorArea.tsx index a13601fa88b..90f51458ece 100644 --- a/packages/@react-spectrum/s2/src/ColorArea.tsx +++ b/packages/@react-spectrum/s2/src/ColorArea.tsx @@ -37,7 +37,8 @@ export const ColorAreaContext = createContext, DOMRefValue>>(null); /** - * A ColorArea allows users to adjust two channels of an RGB, HSL or HSB color value against a two-dimensional gradient background. + * A ColorArea allows users to adjust two channels of an RGB, HSL or HSB color value against a + * two-dimensional gradient background. */ export const ColorArea = forwardRef(function ColorArea( props: ColorAreaProps, diff --git a/packages/@react-spectrum/s2/src/ColorSwatch.tsx b/packages/@react-spectrum/s2/src/ColorSwatch.tsx index 00706595278..5f917a49209 100644 --- a/packages/@react-spectrum/s2/src/ColorSwatch.tsx +++ b/packages/@react-spectrum/s2/src/ColorSwatch.tsx @@ -34,11 +34,13 @@ export interface ColorSwatchProps UnsafeStyles { /** * The size of the ColorSwatch. + * * @default 'M' */ size?: 'XS' | 'S' | 'M' | 'L'; /** * The corner rounding of the ColorSwatch. + * * @default 'default' */ rounding?: 'default' | 'none' | 'full'; diff --git a/packages/@react-spectrum/s2/src/ColorSwatchPicker.tsx b/packages/@react-spectrum/s2/src/ColorSwatchPicker.tsx index 22130c8d855..b4b730d4e87 100644 --- a/packages/@react-spectrum/s2/src/ColorSwatchPicker.tsx +++ b/packages/@react-spectrum/s2/src/ColorSwatchPicker.tsx @@ -31,16 +31,19 @@ export interface ColorSwatchPickerProps children: ReactNode; /** * The amount of padding between the swatches. + * * @default 'regular' */ density?: 'compact' | 'regular' | 'spacious'; /** * The size of the color swatches. + * * @default 'M' */ size?: 'XS' | 'S' | 'M' | 'L'; /** * The corner rounding of the color swatches. + * * @default 'none' */ rounding?: 'none' | 'default' | 'full'; diff --git a/packages/@react-spectrum/s2/src/ComboBox.tsx b/packages/@react-spectrum/s2/src/ComboBox.tsx index 92d94d51453..75208690563 100644 --- a/packages/@react-spectrum/s2/src/ComboBox.tsx +++ b/packages/@react-spectrum/s2/src/ComboBox.tsx @@ -142,9 +142,15 @@ export interface ComboBoxProps * @default 'start' */ align?: 'start' | 'end'; - /** Width of the menu. By default, matches width of the trigger. Note that the minimum width of the dropdown is always equal to the trigger's width. */ + /** + * Width of the menu. By default, matches width of the trigger. Note that the minimum width of the + * dropdown is always equal to the trigger's width. + */ menuWidth?: number; - /** The current loading state of the ComboBox. Determines whether or not the progress circle should be shown. */ + /** + * The current loading state of the ComboBox. Determines whether or not the progress circle should + * be shown. + */ loadingState?: LoadingState; } @@ -377,7 +383,8 @@ export const LOADER_ROW_HEIGHTS = { let InternalComboboxContext = createContext<{size: 'S' | 'M' | 'L' | 'XL'}>({size: 'M'}); /** - * ComboBox allow users to choose a single option from a collapsible list of options when space is limited. + * ComboBox allow users to choose a single option from a collapsible list of options when space is + * limited. */ export const ComboBox = /*#__PURE__*/ (forwardRef as forwardRefType)(function ComboBox< T extends object diff --git a/packages/@react-spectrum/s2/src/ContextualHelp.tsx b/packages/@react-spectrum/s2/src/ContextualHelp.tsx index e86c3e363a7..9e80254240e 100644 --- a/packages/@react-spectrum/s2/src/ContextualHelp.tsx +++ b/packages/@react-spectrum/s2/src/ContextualHelp.tsx @@ -29,7 +29,8 @@ import {useSpectrumContextProps} from './useSpectrumContextProps'; export interface ContextualHelpPopoverProps extends PopoverDialogProps { /** - * The children of the contextual help popover. Supports Heading, Content, and Footer elements. */ + * The children of the contextual help popover. Supports Heading, Content, and Footer elements. + */ children: ReactNode; } @@ -135,6 +136,7 @@ export interface ContextualHelpProps AriaLabelingProps { /** * The placement of the popover with respect to the action button. + * * @default 'bottom start' */ placement?: Placement; @@ -154,7 +156,8 @@ export const ContextualHelpContext = ); /** - * Contextual help shows a user extra information about the state of an adjacent component, or a total view. + * Contextual help shows a user extra information about the state of an adjacent component, or a + * total view. */ export const ContextualHelp = forwardRef(function ContextualHelp( props: ContextualHelpProps, diff --git a/packages/@react-spectrum/s2/src/CustomDialog.tsx b/packages/@react-spectrum/s2/src/CustomDialog.tsx index 63d90fb4a78..36845f9732e 100644 --- a/packages/@react-spectrum/s2/src/CustomDialog.tsx +++ b/packages/@react-spectrum/s2/src/CustomDialog.tsx @@ -41,6 +41,7 @@ export interface CustomDialogProps isKeyboardDismissDisabled?: boolean; /** * The amount of padding around the contents of the dialog. + * * @default 'default' */ padding?: 'default' | 'none'; diff --git a/packages/@react-spectrum/s2/src/DatePicker.tsx b/packages/@react-spectrum/s2/src/DatePicker.tsx index cae4964b185..4dd3d54e565 100644 --- a/packages/@react-spectrum/s2/src/DatePicker.tsx +++ b/packages/@react-spectrum/s2/src/DatePicker.tsx @@ -79,7 +79,9 @@ export interface DatePickerProps */ size?: 'S' | 'M' | 'L' | 'XL'; /** - * The maximum number of months to display at once in the calendar popover, if screen space permits. + * The maximum number of months to display at once in the calendar popover, if screen space + * permits. + * * @default 1 */ maxVisibleMonths?: number; @@ -148,7 +150,8 @@ export const timeField = style({ }); /** - * DatePickers combine a DateField and a Calendar popover to allow users to enter or select a date and time value. + * DatePickers combine a DateField and a Calendar popover to allow users to enter or select a date + * and time value. */ export const DatePicker = /*#__PURE__*/ (forwardRef as forwardRefType)(function DatePicker< T extends DateValue diff --git a/packages/@react-spectrum/s2/src/DateRangePicker.tsx b/packages/@react-spectrum/s2/src/DateRangePicker.tsx index 5d4140677a5..f6c0da712dc 100644 --- a/packages/@react-spectrum/s2/src/DateRangePicker.tsx +++ b/packages/@react-spectrum/s2/src/DateRangePicker.tsx @@ -63,7 +63,9 @@ export interface DateRangePickerProps */ size?: 'S' | 'M' | 'L' | 'XL'; /** - * The maximum number of months to display at once in the calendar popover, if screen space permits. + * The maximum number of months to display at once in the calendar popover, if screen space + * permits. + * * @default 1 */ maxVisibleMonths?: number; diff --git a/packages/@react-spectrum/s2/src/Dialog.tsx b/packages/@react-spectrum/s2/src/Dialog.tsx index 93689106425..49001499ee5 100644 --- a/packages/@react-spectrum/s2/src/Dialog.tsx +++ b/packages/@react-spectrum/s2/src/Dialog.tsx @@ -104,8 +104,9 @@ export const dialogInner = style({ }); /** - * Dialogs are windows containing contextual information, tasks, or workflows that appear over the user interface. - * Depending on the kind of Dialog, further interactions may be blocked until the Dialog is acknowledged. + * Dialogs are windows containing contextual information, tasks, or workflows that appear over the + * user interface. Depending on the kind of Dialog, further interactions may be blocked until the + * Dialog is acknowledged. */ export const Dialog = forwardRef(function Dialog(props: DialogProps, ref: DOMRef) { let {size = 'M', isDismissible, isKeyboardDismissDisabled} = props; diff --git a/packages/@react-spectrum/s2/src/DialogTrigger.tsx b/packages/@react-spectrum/s2/src/DialogTrigger.tsx index 38a0133be8b..cb40f28eae7 100644 --- a/packages/@react-spectrum/s2/src/DialogTrigger.tsx +++ b/packages/@react-spectrum/s2/src/DialogTrigger.tsx @@ -20,9 +20,9 @@ import {ReactNode} from 'react'; export interface DialogTriggerProps extends AriaDialogTriggerProps {} /** - * DialogTrigger serves as a wrapper around a Dialog and its associated trigger, linking the Dialog's - * open state with the trigger's press state. Additionally, it allows you to customize the type and - * positioning of the Dialog. + * DialogTrigger serves as a wrapper around a Dialog and its associated trigger, linking the + * Dialog's open state with the trigger's press state. Additionally, it allows you to customize the + * type and positioning of the Dialog. */ export function DialogTrigger(props: DialogTriggerProps): ReactNode { return ( diff --git a/packages/@react-spectrum/s2/src/Disclosure.tsx b/packages/@react-spectrum/s2/src/Disclosure.tsx index 2a70116de82..21f510d8d46 100644 --- a/packages/@react-spectrum/s2/src/Disclosure.tsx +++ b/packages/@react-spectrum/s2/src/Disclosure.tsx @@ -57,11 +57,13 @@ export interface DisclosureProps StyleProps { /** * The size of the disclosure. + * * @default 'M' */ size?: 'S' | 'M' | 'L' | 'XL'; /** * The amount of space between the disclosures. + * * @default 'regular' */ density?: 'compact' | 'regular' | 'spacious'; @@ -102,7 +104,8 @@ const disclosure = style( ); /** - * A disclosure is a collapsible section of content. It is composed of a header with a heading and trigger button, and a panel that contains the content. + * A disclosure is a collapsible section of content. It is composed of a header with a heading and + * trigger button, and a panel that contains the content. */ export const Disclosure = forwardRef(function Disclosure( props: DisclosureProps, @@ -128,7 +131,8 @@ export const Disclosure = forwardRef(function Disclosure( }); export interface DisclosureTitleProps extends UnsafeStyles, DOMProps { - /** The heading level of the disclosure header. + /** + * The heading level of the disclosure header. * * @default 3 */ @@ -275,7 +279,8 @@ function DisclosureHeaderWithForwardRef(props: DisclosureHeaderProps, ref: DOMRe } /** - * A wrapper element for the disclosure title that can contain other elements not part of the trigger. + * A wrapper element for the disclosure title that can contain other elements not part of the + * trigger. */ export const DisclosureHeader = /*#__PURE__*/ (forwardRef as forwardRefType)( DisclosureHeaderWithForwardRef @@ -354,7 +359,8 @@ const panelInner = style({ }); /** - * A disclosure panel is a collapsible section of content that is hidden until the disclosure is expanded. + * A disclosure panel is a collapsible section of content that is hidden until the disclosure is + * expanded. */ export const DisclosurePanel = forwardRef(function DisclosurePanel( props: DisclosurePanelProps, diff --git a/packages/@react-spectrum/s2/src/Divider.tsx b/packages/@react-spectrum/s2/src/Divider.tsx index 1e6dfd90221..ea83b8aad37 100644 --- a/packages/@react-spectrum/s2/src/Divider.tsx +++ b/packages/@react-spectrum/s2/src/Divider.tsx @@ -30,11 +30,13 @@ import {useSpectrumContextProps} from './useSpectrumContextProps'; interface DividerSpectrumProps { /** * How thick the Divider should be. + * * @default 'M' */ size?: 'S' | 'M' | 'L'; /** * The orientation of the Divider. + * * @default 'horizontal' */ orientation?: 'horizontal' | 'vertical'; diff --git a/packages/@react-spectrum/s2/src/DropZone.tsx b/packages/@react-spectrum/s2/src/DropZone.tsx index 260147fee9d..5b85cf85331 100644 --- a/packages/@react-spectrum/s2/src/DropZone.tsx +++ b/packages/@react-spectrum/s2/src/DropZone.tsx @@ -58,6 +58,7 @@ export interface DropZoneProps isFilled?: boolean; /** * The message to replace the default banner message that is shown when the drop zone is filled. + * * @default 'Drop file to replace' */ replaceMessage?: string; diff --git a/packages/@react-spectrum/s2/src/Form.tsx b/packages/@react-spectrum/s2/src/Form.tsx index b904ccd0b0e..327a423204c 100644 --- a/packages/@react-spectrum/s2/src/Form.tsx +++ b/packages/@react-spectrum/s2/src/Form.tsx @@ -21,6 +21,7 @@ import {useIsSkeleton} from './Skeleton'; interface FormStyleProps extends Omit { /** * Size of the Form elements. + * * @default 'M' */ size?: 'S' | 'M' | 'L' | 'XL'; @@ -67,7 +68,8 @@ export function useFormProps(props: T): T { } /** - * Forms allow users to enter data that can be submitted while providing alignment and styling for form fields. + * Forms allow users to enter data that can be submitted while providing alignment and styling for + * form fields. */ export const Form = /*#__PURE__*/ forwardRef(function Form( props: FormProps, diff --git a/packages/@react-spectrum/s2/src/FullscreenDialog.tsx b/packages/@react-spectrum/s2/src/FullscreenDialog.tsx index 7a2e4590287..000c0a4cb0e 100644 --- a/packages/@react-spectrum/s2/src/FullscreenDialog.tsx +++ b/packages/@react-spectrum/s2/src/FullscreenDialog.tsx @@ -33,7 +33,8 @@ export interface FullscreenDialogProps StyleProps { /** * The variant of fullscreen dialog to display. - * @default "fullscreen" + * + * @default 'fullscreen' */ variant?: 'fullscreen' | 'fullscreenTakeover'; /** Whether pressing the escape key to close the dialog should be disabled. */ @@ -106,7 +107,8 @@ export const dialogInner = style({ }); /** - * Takeover dialogs are large types of dialogs. They use the totality of the screen and should be used for modal experiences with complex workflows. + * Takeover dialogs are large types of dialogs. They use the totality of the screen and should be + * used for modal experiences with complex workflows. */ export const FullscreenDialog = forwardRef(function FullscreenDialog( props: FullscreenDialogProps, diff --git a/packages/@react-spectrum/s2/src/Image.tsx b/packages/@react-spectrum/s2/src/Image.tsx index babdb74c308..0d0a14937b9 100644 --- a/packages/@react-spectrum/s2/src/Image.tsx +++ b/packages/@react-spectrum/s2/src/Image.tsx @@ -30,7 +30,8 @@ export interface ImageSource { */ srcSet?: string | undefined; /** - * The color scheme for this image source. Unlike `media`, this respects the `Provider` color scheme setting. + * The color scheme for this image source. Unlike `media`, this respects the `Provider` color + * scheme setting. */ colorScheme?: 'light' | 'dark'; /** @@ -108,13 +109,13 @@ export interface ImageProps extends UnsafeStyles, SlotProps { /** A function that is called to render a fallback when the image fails to load. */ renderError?: () => ReactNode; /** - * A group of images to coordinate between, matching the group passed to the `` component. - * If not provided, the default image group is used. + * A group of images to coordinate between, matching the group passed to the `` + * component. If not provided, the default image group is used. */ group?: ImageGroup; /** - * Associates the image with a microdata object. - * See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/itemprop). + * Associates the image with a microdata object. See + * [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/itemprop). */ itemProp?: string; } diff --git a/packages/@react-spectrum/s2/src/ImageCoordinator.tsx b/packages/@react-spectrum/s2/src/ImageCoordinator.tsx index 0df4515f5b6..4d169f0200b 100644 --- a/packages/@react-spectrum/s2/src/ImageCoordinator.tsx +++ b/packages/@react-spectrum/s2/src/ImageCoordinator.tsx @@ -13,7 +13,9 @@ export interface ImageCoordinatorProps { /** Children within the ImageCoordinator. */ children: ReactNode; /** - * Time in milliseconds after which images are always displayed, even if all images are not yet loaded. + * Time in milliseconds after which images are always displayed, even if all images are not yet + * loaded. + * * @default 5000 */ timeout?: number; diff --git a/packages/@react-spectrum/s2/src/InlineAlert.tsx b/packages/@react-spectrum/s2/src/InlineAlert.tsx index e76c8224f7e..4361bf760d9 100644 --- a/packages/@react-spectrum/s2/src/InlineAlert.tsx +++ b/packages/@react-spectrum/s2/src/InlineAlert.tsx @@ -43,11 +43,13 @@ export interface InlineAlertProps extends DOMProps, StyleProps, InlineStylesProp interface InlineStylesProps { /** * The semantic tone of a Inline Alert. + * * @default neutral */ variant?: 'informative' | 'positive' | 'notice' | 'negative' | 'neutral'; /** * The visual style of the Inline Alert. + * * @default border */ fillStyle?: 'border' | 'subtleFill' | 'boldFill'; @@ -199,8 +201,8 @@ const content = style({ }); /** - * Inline alerts display a non-modal message associated with objects in a view. - * These are often used in form validation, providing a place to aggregate feedback related to multiple fields. + * Inline alerts display a non-modal message associated with objects in a view. These are often used + * in form validation, providing a place to aggregate feedback related to multiple fields. */ export const InlineAlert = /*#__PURE__*/ forwardRef(function InlineAlert( props: InlineAlertProps, diff --git a/packages/@react-spectrum/s2/src/LabeledValue.tsx b/packages/@react-spectrum/s2/src/LabeledValue.tsx index 4bcfc417611..6357d465295 100644 --- a/packages/@react-spectrum/s2/src/LabeledValue.tsx +++ b/packages/@react-spectrum/s2/src/LabeledValue.tsx @@ -89,6 +89,7 @@ interface ReactElementProps { export interface LabeledValueStyleProps { /** * The size of the component. + * * @default 'M' */ size?: 'S' | 'M' | 'L' | 'XL'; diff --git a/packages/@react-spectrum/s2/src/Link.tsx b/packages/@react-spectrum/s2/src/Link.tsx index a7353f8212d..5a3cc9e59b8 100644 --- a/packages/@react-spectrum/s2/src/Link.tsx +++ b/packages/@react-spectrum/s2/src/Link.tsx @@ -28,6 +28,7 @@ import {useSpectrumContextProps} from './useSpectrumContextProps'; interface LinkStyleProps { /** * The [visual style](https://spectrum.adobe.com/page/link/#Options) of the link. + * * @default 'primary' */ variant?: 'primary' | 'secondary'; diff --git a/packages/@react-spectrum/s2/src/ListView.tsx b/packages/@react-spectrum/s2/src/ListView.tsx index 90337eddb24..d7e4a4a72a0 100644 --- a/packages/@react-spectrum/s2/src/ListView.tsx +++ b/packages/@react-spectrum/s2/src/ListView.tsx @@ -117,11 +117,13 @@ interface ListViewStylesProps { isQuiet?: boolean; /** * How selection should be displayed. + * * @default 'checkbox' */ selectionStyle?: 'highlight' | 'checkbox'; /** * Sets the overflow behavior for item contents. + * * @default 'truncate' */ overflowMode?: 'wrap' | 'truncate'; @@ -206,7 +208,8 @@ const listView = style({ }); /** - * A ListView displays a list of interactive items, and allows a user to navigate, select, or perform an action. + * A ListView displays a list of interactive items, and allows a user to navigate, select, or + * perform an action. */ export const ListView = /*#__PURE__*/ (forwardRef as forwardRefType)(function ListView< T extends object diff --git a/packages/@react-spectrum/s2/src/Menu.tsx b/packages/@react-spectrum/s2/src/Menu.tsx index 0d865dc0fd5..01a17b56cfd 100644 --- a/packages/@react-spectrum/s2/src/Menu.tsx +++ b/packages/@react-spectrum/s2/src/Menu.tsx @@ -791,11 +791,13 @@ function SubmenuTrigger(props: SubmenuTriggerProps): JSX.Element { export interface UnavailableMenuItemTriggerProps { /** - * The contents of the UnavailableMenuItemTrigger. The first child should be a MenuItem and the second child be a ContextualHelpPopover. + * The contents of the UnavailableMenuItemTrigger. The first child should be a MenuItem and the + * second child be a ContextualHelpPopover. */ children: ReactElement[]; /** * Whether the menu item is currently unavailable. + * * @default false */ isUnavailable?: boolean; diff --git a/packages/@react-spectrum/s2/src/Meter.tsx b/packages/@react-spectrum/s2/src/Meter.tsx index 54484e2902e..bbf50c87547 100644 --- a/packages/@react-spectrum/s2/src/Meter.tsx +++ b/packages/@react-spectrum/s2/src/Meter.tsx @@ -25,7 +25,9 @@ import {useDOMRef} from './useDOMRef'; import {useSpectrumContextProps} from './useSpectrumContextProps'; interface MeterStyleProps { - /** The [visual style](https://spectrum.adobe.com/page/meter/#-Options) of the Meter. + /** + * The [visual style](https://spectrum.adobe.com/page/meter/#-Options) of the Meter. + * * @default 'informative' */ variant?: 'informative' | 'positive' | 'notice' | 'negative'; @@ -41,6 +43,7 @@ interface MeterStyleProps { staticColor?: 'white' | 'black' | 'auto'; /** * The label's overall position relative to the element it is labeling. + * * @default 'top' */ labelPosition?: LabelPosition; diff --git a/packages/@react-spectrum/s2/src/NumberField.tsx b/packages/@react-spectrum/s2/src/NumberField.tsx index ca83a5275b1..eef3c41bee2 100644 --- a/packages/@react-spectrum/s2/src/NumberField.tsx +++ b/packages/@react-spectrum/s2/src/NumberField.tsx @@ -69,6 +69,7 @@ export interface NumberFieldProps Pick { /** * Whether to hide the increment and decrement buttons. + * * @default false */ hideStepper?: boolean; @@ -164,7 +165,8 @@ const stepperContainerStyles = style({ }); /** - * NumberFields allow users to input number values with a keyboard or increment/decrement with step buttons. + * NumberFields allow users to input number values with a keyboard or increment/decrement with step + * buttons. */ export const NumberField = forwardRef(function NumberField( props: NumberFieldProps, diff --git a/packages/@react-spectrum/s2/src/Picker.tsx b/packages/@react-spectrum/s2/src/Picker.tsx index 4e7dc1350ee..d34e26c56e2 100644 --- a/packages/@react-spectrum/s2/src/Picker.tsx +++ b/packages/@react-spectrum/s2/src/Picker.tsx @@ -151,12 +151,16 @@ export interface PickerProps({size: let InsideSelectValueContext = createContext(false); /** - * Pickers allow users to choose a single option from a collapsible list of options when space is limited. + * Pickers allow users to choose a single option from a collapsible list of options when space is + * limited. */ export const Picker = /*#__PURE__*/ (forwardRef as forwardRefType)(function Picker< T extends object, diff --git a/packages/@react-spectrum/s2/src/Popover.tsx b/packages/@react-spectrum/s2/src/Popover.tsx index f4181529965..6ead949d693 100644 --- a/packages/@react-spectrum/s2/src/Popover.tsx +++ b/packages/@react-spectrum/s2/src/Popover.tsx @@ -303,6 +303,7 @@ export interface PopoverDialogProps children?: ReactNode; /** * The amount of padding around the contents of the dialog. + * * @default 'default' */ padding?: 'default' | 'none'; diff --git a/packages/@react-spectrum/s2/src/ProgressBar.tsx b/packages/@react-spectrum/s2/src/ProgressBar.tsx index f9925fae436..426888f88d4 100644 --- a/packages/@react-spectrum/s2/src/ProgressBar.tsx +++ b/packages/@react-spectrum/s2/src/ProgressBar.tsx @@ -45,6 +45,7 @@ interface ProgressBarStyleProps { staticColor?: 'white' | 'black' | 'auto'; /** * The label's overall position relative to the element it is labeling. + * * @default 'top' */ labelPosition?: LabelPosition; @@ -168,8 +169,8 @@ const indeterminateAnimation = style({ }); /** - * ProgressBars show the progression of a system operation: downloading, uploading, processing, etc., in a visual way. - * They can represent either determinate or indeterminate progress. + * ProgressBars show the progression of a system operation: downloading, uploading, processing, + * etc., in a visual way. They can represent either determinate or indeterminate progress. */ export const ProgressBar = /*#__PURE__*/ forwardRef(function ProgressBar( props: ProgressBarProps, diff --git a/packages/@react-spectrum/s2/src/ProgressCircle.tsx b/packages/@react-spectrum/s2/src/ProgressCircle.tsx index 61854b8b845..837d6b4d145 100644 --- a/packages/@react-spectrum/s2/src/ProgressCircle.tsx +++ b/packages/@react-spectrum/s2/src/ProgressCircle.tsx @@ -159,8 +159,8 @@ const dashoffsetAnimation = keyframes(` `); /** - * ProgressCircles show the progression of a system operation such as downloading, uploading, or processing, in a visual way. - * They can represent determinate or indeterminate progress. + * ProgressCircles show the progression of a system operation such as downloading, uploading, or + * processing, in a visual way. They can represent determinate or indeterminate progress. */ export const ProgressCircle = /*#__PURE__*/ forwardRef(function ProgressCircle( props: ProgressCircleProps, diff --git a/packages/@react-spectrum/s2/src/Provider.tsx b/packages/@react-spectrum/s2/src/Provider.tsx index 24967b11b5d..02a5d8d253e 100644 --- a/packages/@react-spectrum/s2/src/Provider.tsx +++ b/packages/@react-spectrum/s2/src/Provider.tsx @@ -32,13 +32,15 @@ export interface ProviderProps extends UnsafeStyles, DOMProps { /** The content of the Provider. */ children: ReactNode; /** - * The locale for your application as a [BCP 47](https://www.ietf.org/rfc/bcp/bcp47.txt) language code. - * Defaults to the browser/OS language setting. + * The locale for your application as a [BCP 47](https://www.ietf.org/rfc/bcp/bcp47.txt) language + * code. Defaults to the browser/OS language setting. + * * @default 'en-US' */ locale?: string; /** - * Provides a client side router to all nested React Spectrum links to enable client side navigation. + * Provides a client side router to all nested React Spectrum links to enable client side + * navigation. */ router?: Router; /** @@ -52,6 +54,7 @@ export interface ProviderProps extends UnsafeStyles, DOMProps { styles?: StyleString; /** * The DOM element to render. + * * @default div */ elementType?: keyof JSX.IntrinsicElements; diff --git a/packages/@react-spectrum/s2/src/RangeCalendar.tsx b/packages/@react-spectrum/s2/src/RangeCalendar.tsx index 67307de46a5..d270c259bb6 100644 --- a/packages/@react-spectrum/s2/src/RangeCalendar.tsx +++ b/packages/@react-spectrum/s2/src/RangeCalendar.tsx @@ -49,6 +49,7 @@ export interface RangeCalendarProps errorMessage?: ReactNode; /** * The number of months to display at once. + * * @default 1 */ visibleMonths?: number; @@ -95,7 +96,8 @@ const calendarStyles = style<{isMultiMonth?: boolean}>( ); /** - * RangeCalendars display a grid of days in one or more months and allow users to select a contiguous range of dates. + * RangeCalendars display a grid of days in one or more months and allow users to select a + * contiguous range of dates. */ export const RangeCalendar = /*#__PURE__*/ (forwardRef as forwardRefType)(function RangeCalendar< T extends DateValue diff --git a/packages/@react-spectrum/s2/src/RangeSlider.tsx b/packages/@react-spectrum/s2/src/RangeSlider.tsx index dadb9c31865..6469ace4652 100644 --- a/packages/@react-spectrum/s2/src/RangeSlider.tsx +++ b/packages/@react-spectrum/s2/src/RangeSlider.tsx @@ -34,11 +34,13 @@ import {useSpectrumContextProps} from './useSpectrumContextProps'; export interface RangeSliderProps extends Omit>, 'children'> { /** - * The name of the start input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). + * The name of the start input element, used when submitting an HTML form. See + * [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). */ startName?: string; /** - * The name of the end input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). + * The name of the end input element, used when submitting an HTML form. See + * [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). */ endName?: string; /** @@ -53,7 +55,8 @@ export const RangeSliderContext = createContext, FocusableRefValue>>(null); /** - * RangeSliders allow users to quickly select a subset range. They should be used when the upper and lower bounds to the range are invariable. + * RangeSliders allow users to quickly select a subset range. They should be used when the upper and + * lower bounds to the range are invariable. */ export const RangeSlider = /*#__PURE__*/ forwardRef(function RangeSlider( props: RangeSliderProps, diff --git a/packages/@react-spectrum/s2/src/SelectBoxGroup.tsx b/packages/@react-spectrum/s2/src/SelectBoxGroup.tsx index 6cc18eea904..bc236199eec 100644 --- a/packages/@react-spectrum/s2/src/SelectBoxGroup.tsx +++ b/packages/@react-spectrum/s2/src/SelectBoxGroup.tsx @@ -50,11 +50,13 @@ export interface SelectBoxGroupProps children: ReactNode | ((item: T) => ReactNode); /** * The layout direction of the content in each SelectBox. + * * @default 'vertical' */ orientation?: Orientation; /** * The selection mode for the SelectBoxGroup. + * * @default 'single' */ selectionMode?: 'single' | 'multiple'; diff --git a/packages/@react-spectrum/s2/src/SkeletonCollection.tsx b/packages/@react-spectrum/s2/src/SkeletonCollection.tsx index 0a687c8fec2..af24887af26 100644 --- a/packages/@react-spectrum/s2/src/SkeletonCollection.tsx +++ b/packages/@react-spectrum/s2/src/SkeletonCollection.tsx @@ -26,7 +26,8 @@ class SkeletonNode extends CollectionNode { } /** - * A SkeletonCollection generates placeholder content within a collection component such as CardView. + * A SkeletonCollection generates placeholder content within a collection component such as + * CardView. */ export const SkeletonCollection = createLeafComponent( SkeletonNode, diff --git a/packages/@react-spectrum/s2/src/Slider.tsx b/packages/@react-spectrum/s2/src/Slider.tsx index e207d3e4cc4..002595f522a 100644 --- a/packages/@react-spectrum/s2/src/Slider.tsx +++ b/packages/@react-spectrum/s2/src/Slider.tsx @@ -444,7 +444,8 @@ export function SliderBase( } /** - * Sliders allow users to quickly select a value within a range. They should be used when the upper and lower bounds to the range are invariable. + * Sliders allow users to quickly select a value within a range. They should be used when the upper + * and lower bounds to the range are invariable. */ export const Slider = /*#__PURE__*/ forwardRef(function Slider( props: SliderProps, diff --git a/packages/@react-spectrum/s2/src/TableView.tsx b/packages/@react-spectrum/s2/src/TableView.tsx index 6ddd5b9e841..7405a04b7af 100644 --- a/packages/@react-spectrum/s2/src/TableView.tsx +++ b/packages/@react-spectrum/s2/src/TableView.tsx @@ -135,11 +135,13 @@ interface S2TableProps { isQuiet?: boolean; /** * Sets the amount of vertical padding within each cell. + * * @default 'regular' */ density?: 'compact' | 'spacious' | 'regular'; /** * Sets the overflow behavior for the cell contents. + * * @default 'truncate' */ overflowMode?: 'wrap' | 'truncate'; @@ -358,7 +360,8 @@ export const TableContext = createContext, DOMRefValue>>(null); /** - * Tables are containers for displaying information. They allow users to quickly scan, sort, compare, and take action on large amounts of data. + * Tables are containers for displaying information. They allow users to quickly scan, sort, + * compare, and take action on large amounts of data. */ export const TableView = forwardRef(function TableView( props: TableViewProps, @@ -652,6 +655,7 @@ export interface ColumnProps extends Omit< allowsResizing?: boolean; /** * The alignment of the column's contents relative to its allotted width. + * * @default 'start' */ align?: 'start' | 'center' | 'end'; diff --git a/packages/@react-spectrum/s2/src/Tabs.tsx b/packages/@react-spectrum/s2/src/Tabs.tsx index 897475abc3d..bb3ba797fd4 100644 --- a/packages/@react-spectrum/s2/src/Tabs.tsx +++ b/packages/@react-spectrum/s2/src/Tabs.tsx @@ -80,12 +80,14 @@ export interface TabsProps children: ReactNode; /** * The amount of space between the tabs. + * * @default 'regular' */ density?: 'compact' | 'regular'; /** * Defines if the text within the tabs should be hidden and only the icon should be shown. * The text is always visible when the item is collapsed into a picker. + * * @default 'show' */ labelBehavior?: 'show' | 'hide'; @@ -174,7 +176,8 @@ const tabs = style( ); /** - * Tabs organize content into multiple sections and allow users to navigate between them. The content under the set of tabs should be related and form a coherent unit. + * Tabs organize content into multiple sections and allow users to navigate between them. The + * content under the set of tabs should be related and form a coherent unit. */ export const Tabs = forwardRef(function Tabs(props: TabsProps, ref: DOMRef) { [props, ref] = useSpectrumContextProps(props, ref, TabsContext); diff --git a/packages/@react-spectrum/s2/src/TabsPicker.tsx b/packages/@react-spectrum/s2/src/TabsPicker.tsx index f9033785906..654418090b8 100644 --- a/packages/@react-spectrum/s2/src/TabsPicker.tsx +++ b/packages/@react-spectrum/s2/src/TabsPicker.tsx @@ -63,12 +63,16 @@ export interface PickerProps * @default 'start' */ align?: 'start' | 'end'; - /** Width of the menu. By default, matches width of the trigger. Note that the minimum width of the dropdown is always equal to the trigger's width. */ + /** + * Width of the menu. By default, matches width of the trigger. Note that the minimum width of the + * dropdown is always equal to the trigger's width. + */ menuWidth?: number; /** Density of the tabs, affects the height of the picker. */ density: 'compact' | 'regular'; /** * If the tab picker should only display icon and no text for the button label. + * * @default 'show */ labelBehavior?: 'show' | 'hide'; @@ -305,7 +309,8 @@ function Picker(props: PickerProps, ref: FocusableRef isInvalid?: boolean; /** An error message for the field. */ errorMessage?: ReactNode; - /** Limit the number of rows initially shown. This will render a button that allows the user to expand to show all tags. */ + /** + * Limit the number of rows initially shown. This will render a button that allows the user to + * expand to show all tags. + */ maxRows?: number; - /** The label to display on the action button. */ + /** The label to display on the action button. */ groupActionLabel?: string; /** Handler that is called when the action button is pressed. */ onGroupAction?: () => void; @@ -122,7 +125,10 @@ export const TagGroupContext = const InternalTagGroupContext = createContext>({}); -/** Tags allow users to categorize content. They can represent keywords or people, and are grouped to describe an item or a search request. */ +/** + * Tags allow users to categorize content. They can represent keywords or people, and are grouped to + * describe an item or a search request. + */ export const TagGroup = /*#__PURE__*/ (forwardRef as forwardRefType)(function TagGroup< T extends object >(props: TagGroupProps, ref: DOMRef) { diff --git a/packages/@react-spectrum/s2/src/Toast.tsx b/packages/@react-spectrum/s2/src/Toast.tsx index 02404e0d72a..70331df53eb 100644 --- a/packages/@react-spectrum/s2/src/Toast.tsx +++ b/packages/@react-spectrum/s2/src/Toast.tsx @@ -55,7 +55,8 @@ export interface ToastContainerProps extends Omit< > { /** * Placement of the toast container on the page. - * @default "bottom" + * + * @default 'bottom' */ placement?: ToastPlacement; } diff --git a/packages/@react-spectrum/s2/src/ToggleButton.tsx b/packages/@react-spectrum/s2/src/ToggleButton.tsx index 8624d751f75..9e90ffc3713 100644 --- a/packages/@react-spectrum/s2/src/ToggleButton.tsx +++ b/packages/@react-spectrum/s2/src/ToggleButton.tsx @@ -49,7 +49,10 @@ export interface ToggleButtonProps ActionButtonStyleProps { /** The content to display in the button. */ children: ReactNode; - /** Whether the button should be displayed with an [emphasized style](https://spectrum.adobe.com/page/action-button/#Emphasis). */ + /** + * Whether the button should be displayed with an [emphasized + * style](https://spectrum.adobe.com/page/action-button/#Emphasis). + */ isEmphasized?: boolean; } diff --git a/packages/@react-spectrum/s2/src/ToggleButtonGroup.tsx b/packages/@react-spectrum/s2/src/ToggleButtonGroup.tsx index 21e3c99b24d..e447bfe3c57 100644 --- a/packages/@react-spectrum/s2/src/ToggleButtonGroup.tsx +++ b/packages/@react-spectrum/s2/src/ToggleButtonGroup.tsx @@ -30,7 +30,10 @@ export interface ToggleButtonGroupProps 'children' | 'style' | 'className' | 'render' | keyof GlobalDOMAttributes >, DOMProps { - /** Whether the button should be displayed with an [emphasized style](https://spectrum.adobe.com/page/action-button/#Emphasis). */ + /** + * Whether the button should be displayed with an [emphasized + * style](https://spectrum.adobe.com/page/action-button/#Emphasis). + */ isEmphasized?: boolean; } diff --git a/packages/@react-spectrum/s2/src/TreeView.tsx b/packages/@react-spectrum/s2/src/TreeView.tsx index 18e11d145c9..eb081c137ce 100644 --- a/packages/@react-spectrum/s2/src/TreeView.tsx +++ b/packages/@react-spectrum/s2/src/TreeView.tsx @@ -69,7 +69,10 @@ interface S2TreeProps { interface TreeViewStyleProps { /** - * How selection should be displayed. For guidance on when to use which option, refer to the [Spectrum](https://spectrum.adobe.com/page/tree-view/#Checkbox-or-highlight-selection-style) page. + * How selection should be displayed. For guidance on when to use which option, refer to the + * [Spectrum](https://spectrum.adobe.com/page/tree-view/#Checkbox-or-highlight-selection-style) + * page. + * * @default 'checkbox' */ selectionStyle?: 'highlight' | 'checkbox'; diff --git a/packages/@react-spectrum/s2/src/pressScale.ts b/packages/@react-spectrum/s2/src/pressScale.ts index ecc777535ee..b7819fec1b5 100644 --- a/packages/@react-spectrum/s2/src/pressScale.ts +++ b/packages/@react-spectrum/s2/src/pressScale.ts @@ -17,23 +17,21 @@ import {CSSProperties, RefObject} from 'react'; * Returns a render prop style function that applies a subtle Spectrum "press" scale * effect to an element while it is being pressed. * + * @example + * import {Button} from 'react-aria-components/Button'; + * import {pressScale} from '@react-spectrum/s2'; + * import {useRef} from 'react'; + * + * function MyButton(props) { + * let ref = useRef(null); + * return