test: testing ai instructions

amanabiy · amanabiy · commit c19a02890f23 · 2026-03-09T13:27:18.000+01:00
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,13 @@
+React component library for [Cloudscape Design System](https://cloudscape.design/) — an open source design system for building accessible, inclusive web experiences at scale.
+
+To install dependencies use `npm install`
+Build with `npm run quick-build` for dev, or `npm run build` for a full production build.
+
+For component structure, props, events, and refs, see docs/COMPONENT_CONVENTIONS.md.
+For design tokens, CSS rules, and RTL support, see docs/STYLING.md.
+For test commands, see docs/TESTING.md.
+For writing tests and test utils, see docs/WRITING_TESTS.md.
+For prettier, stylelint, and eslint (`npm run lint`), see docs/CODE_STYLE.md.
+For dev/test pages, see docs/DEV_PAGES.md.
+For API documentation comments, see docs/API_DOCS.md.
+For internal shared utilities, see docs/INTERNALS.md.
diff --git a/docs/API_DOCS.md b/docs/API_DOCS.md
@@ -0,0 +1,10 @@
+# API Documentation Comments
+
+This project uses `@cloudscape-design/documenter` to generate API docs from JSDoc comments in component interface files (`src/<component>/interfaces.ts`).
+
+## Special tags
+
+- `@i18n` — marks internationalization properties
+- `@analytics` — marks analytics metadata properties
+- `@deprecated` — marks deprecated properties (include replacement info)
+- `@displayname` — overrides the display name (e.g. `children` → `text`)
diff --git a/docs/CODE_STYLE.md b/docs/CODE_STYLE.md
@@ -0,0 +1,18 @@
+# Code Style
+
+This project enforces formatting and linting via prettier, stylelint, and eslint. Run `npm run lint` to check everything.
+
+Before writing or modifying code, read the relevant config files:
+
+- Prettier: `.prettierrc`
+- Stylelint: `.stylelintrc`
+- ESLint: `eslint.config.mjs`
+
+Follow whatever rules are defined there. Do not guess — read the configs.
+
+All source files must include the license header:
+
+```
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+```
diff --git a/docs/COMPONENT_CONVENTIONS.md b/docs/COMPONENT_CONVENTIONS.md
@@ -0,0 +1,65 @@
+# Component Conventions
+
+## Ground Rules
+
+- Always read existing code for the component you're working on before writing new code. For new components, pick a similar one as your template.
+- Inner HTML structure and class names are not public API — don't rely on them.
+
+## Component Structure
+
+Each public component lives in `src/<component-name>/index.tsx` and must:
+
+- Assign default prop values in the destructuring signature (not `defaultProps`), then pass them explicitly to the internal component
+- Call `useBaseComponent` for telemetry — pass `props` (primitive/enum values with defaults applied) and optionally `metadata` (derived counters or booleans). No state props, no PII, no user input strings.
+- Use `getExternalProps` or `getBaseProps` to strip internal `__`-prefixed props
+- Call `applyDisplayName` at the bottom of the file
+- Export the props interface as `${ComponentName}Props`
+
+Each public component has a private counterpart at `src/<component-name>/internal.tsx` for composition. Internal props are prefixed with `__`. The public component must not add behavior beyond what the internal component provides.
+
+Shared hooks, components, contexts, and helpers live in `src/internal/`. Always check there before building new shared code.
+
+## Props & Interfaces
+
+- Props interface: `${ComponentName}Props`, namespace sub-types under it (e.g. `${ComponentName}Props.Variant`)
+- Union types must be type aliases (no inline unions)
+- Array types must use `ReadonlyArray<T>`
+- Cast string props to string at runtime if rendered in JSX — React accepts JSX content there
+- Component return type must be exactly `JSX.Element` — `null` or arrays break the doc generator
+- Components exported as default from `index.tsx` are public; everything else is private
+
+## Events
+
+- Use `CancelableEventHandler<DetailType>` or `NonCancelableEventHandler<DetailType>` from `../internal/events`
+- All `on*` props must use these interfaces (build fails otherwise)
+
+## Refs
+
+- Expose via `${ComponentName}Props.Ref` interface
+- Use `useForwardFocus(ref, elementRef)` for simple focus delegation
+- For `React.forwardRef` generics, create a `${ComponentName}ForwardRefType` interface
+
+## Controllable Components
+
+- Controlled: requires `value` + `onChange` (e.g. Input)
+- Uncontrolled: internal state only (e.g. dropdown open)
+- Controllable: uncontrolled by default, controlled when `value` is set
+
+Use `useControllable` — read existing components for the pattern.
+
+## Element Queries
+
+Use `useContainerBreakpoints` instead of CSS media queries. Handle `null` on first render.
+
+## I18n
+
+Three string categories:
+- Static → `i18nStrings` property
+- Dynamic → functions in `i18nStrings` returning strings
+- Context-dependent → top-level props (out of scope for i18n provider)
+
+Use `useInternalI18n('<component>')` to consume. Test with `TestI18nProvider` from `src/i18n/testing`.
+
+## Dependencies
+
+Before adding any dependency: must support React 16.8+ and latest 3 major Chrome/Firefox/Edge, no global state, ESM preferred, no external resources (CSP).
diff --git a/docs/DEV_PAGES.md b/docs/DEV_PAGES.md
@@ -0,0 +1,11 @@
+# Dev Pages
+
+Dev and test pages live in `pages/<component-name>/`. They are used for local development, integration tests, and visual regression tests.
+
+## Rules
+
+- Export a default function component
+- Import components via `~components/<name>` (not relative paths to `src/`)
+- For visual regression content, either use `SimplePage` from `pages/app/templates` (handles heading, screenshot area, i18n, and layout) or wrap content in `ScreenshotArea` from `pages/utils/screenshot-area` with a manual `<h1>`
+- Use `createPermutations` and `PermutationsView` from `pages/utils/` for permutation pages
+- If multiple pages share data (like `i18nStrings`), put it in a `common.tsx` in the same directory
diff --git a/docs/INTERNALS.md b/docs/INTERNALS.md
@@ -0,0 +1,16 @@
+# Internal Utilities
+
+Shared infrastructure lives in `src/internal/`.
+
+## What's in there
+
+- `hooks/` — shared React hooks (component telemetry, controllable state, focus management, container/element queries, visual mode detection, intersection observers, debounce/throttle, etc.)
+- `components/` — shared internal UI building blocks (dropdowns, options, focus locks, tooltips, chart primitives, transitions, screen-reader utilities, drag handles, etc.)
+- `context/` — React contexts for cross-component communication (form fields, modals, split panels, container headers, etc.)
+- `utils/` — pure helper functions (DOM helpers, key handling, date/time, locale, display names, prop stripping, etc.)
+- `events/` — event handler type definitions used by all component `on*` props
+- `base-component/` — base prop extraction utilities
+- `styles/` — shared SCSS mixins
+- `analytics/` — telemetry and funnel metrics
+
+Always check `src/internal/` before introducing new utilities, hooks, or shared components.
diff --git a/docs/STYLING.md b/docs/STYLING.md
@@ -0,0 +1,26 @@
+# Styling
+
+Never hardcode CSS spacing, colors, borders, shadows, typography, or motion values. This project uses design tokens and custom CSS properties.
+
+## Design Tokens
+
+Tokens are defined in `style-dictionary/` and consumed in SCSS via the `awsui` namespace.
+
+## Custom CSS Properties
+
+Custom CSS properties are defined in `build-tools/utils/custom-css-properties.js`. Read this file to see what's available.
+
+## Rules
+
+- Apply `styles-reset` mixin on every root element — prevents parent styles from leaking in
+- Root elements must not have outer margins — spacing is managed by parent components
+- No descendant combinators (`.a .b` with a space) — breaks CSS scoping
+- Wrap all animations in the `with-motion` mixin — ensures motion can be toggled
+- Use logical properties only — no `left`/`right`/`top`/`bottom`/`width`/`height` in CSS. Use `inline-start`/`inline-end`/`block-start`/`block-end`/`inline-size`/`block-size` instead. This is required for RTL support.
+
+## RTL Support
+
+For bidirectional layout support, use the internal RTL utilities in `src/internal/`:
+
+- SCSS: `with-direction` mixin for direction-aware styles
+- JS: `getIsRtl` for detecting direction, `handleKey` for direction-aware key handling, `getLogicalBoundingClientRect` / `getOffsetInlineStart` / `getScrollInlineStart` for direction-aware measurements
diff --git a/docs/TESTING.md b/docs/TESTING.md
@@ -0,0 +1,37 @@
+# Testing
+
+## Quick Reference
+
+```
+npm test               # all tests (unit + integ + a11y)
+npm run test:unit      # unit + build-tool tests
+npm run test:integ     # integration tests (starts dev server automatically)
+npm run test:motion    # motion tests (starts dev server automatically)
+npm run test:a11y      # accessibility tests
+```
+
+The npm scripts use gulp tasks that handle env vars (`TZ=UTC`, `NODE_OPTIONS=--experimental-vm-modules`) and dev server lifecycle automatically.
+
+## Targeting Specific Files
+
+For running a specific test file or folder, call jest directly with the appropriate config:
+
+```
+# Unit
+TZ=UTC node_modules/.bin/jest -c jest.unit.config.js src/button/__tests__/button.test.tsx
+
+# Integration (requires dev server running via `npm start`)
+NODE_OPTIONS=--experimental-vm-modules node_modules/.bin/jest -c jest.integ.config.js src/input/__integ__/
+
+# Motion (requires dev server running via `npm start`)
+NODE_OPTIONS=--experimental-vm-modules node_modules/.bin/jest -c jest.motion.config.js src/flashbar/__motion__/
+
+# Build-tool / stylelint
+NODE_OPTIONS=--experimental-vm-modules node_modules/.bin/jest -c jest.build-tools.config.js build-tools/stylelint
+```
+
+## Updating Snapshots
+
+```
+TZ=UTC node_modules/.bin/jest -u -c jest.unit.config.js src/__tests__/snapshot-tests/
+```
diff --git a/docs/WRITING_TESTS.md b/docs/WRITING_TESTS.md
@@ -0,0 +1,31 @@
+# Writing Tests
+
+## Test Utils
+
+Use the project's test utils in `src/test-utils/` — don't query the DOM directly.
+
+- `src/test-utils/dom/` — unit test wrappers (JSDOM)
+- `src/test-utils/selectors/` — integration test wrappers (real browser)
+
+Read the wrapper for the component you're testing to see available `find*` methods.
+
+### Authoring Test Utils
+
+Each wrapper extends `ComponentWrapper`, has a static `rootSelector`, and explicit return types on all methods. Test-util CSS classes go in `src/<component-name>/test-classes/styles.scss`. Read existing wrappers for the pattern.
+
+## Unit Tests
+
+Use `react-testing-library` to render, combined with test-utils. Prefer test-utils for public interactions, react-testing-library for internal corner cases. Read an existing test file for the setup pattern.
+
+## Integration Tests
+
+Use `useBrowser` from `@amzn/awsui-browser-test-tools/use-browser`. Use a `setupTest` wrapper with `waitForVisible`. Don't wait on tag name selectors — they're visible before JS loads. Multiple assertions per test are fine (e2e tests are slow). Use page object pattern for files with many tests.
+
+## I18n Testing
+
+Test `useInternalI18n` with `TestI18nProvider` from `src/i18n/testing`. Read existing i18n tests for the pattern.
+
+## Gotchas
+
+- `findAll`/`findAllByClassName` with `.get()` uses `:nth-child()` — only works if items share the same parent node
+- All dev pages are axe-checked automatically. A11y violations fail the build. Checks run in dark mode only.
