@atlaskit/top-layer 0.17.0 → 1.0.0

package/AGENTS.md

@@ -0,0 +1,113 @@
+## General
+
+In your language in comments, and user facing copy, please avoid em-dashes and contractions (prefer
+"do not" over "don't")
+
+## TypeScript authoring patterns:
+
+- Avoid `any`. Always look for opportunities to have more accurate types
+- Avoid `switch` statements, prefer `if` statements in functions with early returns
+- Avoid conditional assignment of variables. (Use functions, IIFE, etc. to avoid needing to use
+  `let`)
+- Avoid nested ternaries. Extract to a function with early returns instead.
+- Prefer explicit conversions for types (e.g. `Boolean(value)` and not `!!value` for booleans,
+  `Number(value)` for numbers, and `String(value)` for strings. For strings you can also use
+  template literals)
+- Never use `for` with missing parameters, e.g. `for(;;)`. Use other clearer patterns (`while(true)`
+  in this case)
+- Prefer function definitions `function getName(){}` over function assignment
+  `const getName = function(){}`.
+- Do not author `class`. For stateful constructs, use a factory function that closes over its state
+  and returns a plain object (e.g. `createClaudeClient({ apiKey })` instead of
+  `new ClaudeClient(apiKey)`). Third-party classes you must instantiate (e.g. SDK clients) are fine
+  to `new` inside the factory.
+- Prefer inline exports (`export function`, `export const`) over grouped `export { ... }` blocks at
+  the bottom of a file. This is also true for default exports (eg
+  `default export function hello(){}`)
+- Prefer discriminated unions for result types `{type: 'error', message: string}` over
+  `{error: true, message?: string}`
+- Avoid the `void` keyword: do not use `void` as a return type annotation (use explicit return types
+  or omit), and do not use the `void` operator (e.g. `void someExpression()`). You can use
+  `Promise<void>` though.
+- For functions that might return values, prefer functions that return an explicit `null` over
+  `undefined`.
+- For function parameters, prefer named arguments (e.g. a single destructured options object) over
+  positional parameters, even for single-parameter functions
+- Avoid regex when a clearer approach exists; use it when it would greatly simplify things.
+- If a module needs a helper function, put it above the caller. Ideally do not rely on hoisting
+- Always use blocks for conditions, do not do inline conditionals like
+  `if(condition) doSomething();`
+- Do not use non null assertions (e.g. `value!.condition`). Use `invariant` from `tiny-invariant`
+  (if the value should be there), or optional chaining (if it legitimately could be `null`)
+- When adding listeners to raw `EventTarget` objects (outside JSX), use `bind-event-listener`
+- When a function has cleanup actions (unsubscribe, cancel, teardown), return a cleanup function
+  (`TCleanupFn` from `@/types`). This mirrors the `useEffect` cleanup pattern
+- Use optional chaining
+- For arrays, prefer array methods (eg `map`, `filter` and `reduce`) over manual looping
+- Start type names with a `T` to make it clear they are types.
+- Avoid abbreviated variable names. Use descriptive names that read clearly (e.g. `transaction` not
+  `tx`, `user` not `u`, `config` not `cfg`, `event` not `e`). This applies to all variables
+  including lambda/callback parameters. Exceptions: `ctx` for canvas/React contexts, and `a`/`b` in
+  sort comparators.
+- For unused parameters or variables, prefix with `_` (e.g. `(_, index) => ...`, or `_unusedName` if
+  a descriptive marker reads better). ESLint accepts this via `argsIgnorePattern: '^_'`. Do not
+  invent placeholder names like `unused`.
+- When making functions that return booleans, always prefer function names that express a positive.
+  `function isValidUser():boolean {}` and not `function isInvalidUser(): boolean {}`
+- Prefer TypeScript `type` over `interface` unless there is functionality that requires an
+  `interface`
+
+## In code comments
+
+- Place comments on the line directly above the code they describe. Never place comments to the
+  right of code on the same line.
+- Code comments should be minimal, clear and accurate
+- Add code comments for anything that is non-obvious by looking at the code
+- Use `// comment` for single-line comments. Use JSDoc-style for multi-line documentation comments
+  (markdown is encouraged inside)
+- Do not use decorative separator comments (e.g. `// ── Section ──`, `// ───────...`). Use a plain
+  `// Section` comment instead or JSDoc blocks for larger comments:
+
+  ```ts
+  /**
+   * **Bold title**
+   *
+   * Some more content goes here
+   */`
+  ```
+
+## React rules
+
+- Always use named functions for components (eg `export function App() {})`
+- Prefer discriminated unions to model state, rather than having disconnected pieces of state. This
+  is the React embodiment of the discriminated unions rule in the TypeScript section above
+- Do not add `className` or `style` props to components as they are unbounded APIs
+- `forwardRef` is needed as this is a `react@18+` project.
+
+```ts
+// Do not do this:
+const [isLoading, setIsLoading] = useState(false);
+const [loaded, setLoaded] = useState(false);
+
+// Prefer discriminated unions, which makes illegal states impossible:
+type TState =
+	| { type: 'idle' }
+	| {
+			type: 'loading';
+	  }
+	| {
+			type: 'loaded';
+	  };
+const [state, setState] = useState<TState>({ type: 'idle' });
+```
+
+- Do not export class name strings from files (e.g. no `export const cardClasses = '...'`)
+- Never call a function from a parent context (e.g. a context action, a prop callback) during render
+  to update that parent's state. This causes React's "Cannot update a component while rendering a
+  different component" error. Use `useEffect` instead. Updating local state during render (the
+  getDerivedStateFromProps pattern) is fine.
+- If a react component needs to return a type, it should be `ReactNode` and not a JSX type.
+
+## Versioning
+
+This package is still on `0.x` releases. All changes should be a `minor` (`0.x`) release.

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @atlaskit/top-layer
 
+## 1.0.0
+
+### Major Changes
+
+- [`f2dc9097319f0`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/f2dc9097319f0) - ###
+  Dropped support for _legacy_ Typescript 4 types. **Typescript 5 is now the new minimum**.
+
+  Removes the `typesVersions` property and `dist/types-ts4.5` directory from the dist.
+
+  Types are now exclusively via the `"types": "dist/types/index.d.ts"` property.
+
+  ```diff
+  - "typesVersions": {
+  -    ">=4.5 <4.9": {
+  -        "*": [
+  -            "dist/types-ts4.5/*",
+  -            "dist/types-ts4.5/index.d.ts"
+  -        ]
+  -    }
+  - },
+  ```
+
+### Patch Changes
+
+- Updated dependencies
+
+## 0.18.0
+
+### Minor Changes
+
+- [`b7ed2b39d3ef8`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/b7ed2b39d3ef8) -
+  Internal: align code with package conventions. No functional changes
+
 ## 0.17.0
 
 ### Minor Changes

package/animations/package.json

@@ -6,12 +6,5 @@
   "sideEffects": [
     "*.compiled.css"
   ],
-  "types": "../dist/types/entry-points/animations.d.ts",
-  "typesVersions": {
-    ">=4.5 <5.9": {
-      "*": [
-        "../dist/types-ts4.5/entry-points/animations.d.ts"
-      ]
-    }
-  }
+  "types": "../dist/types/entry-points/animations.d.ts"
 }

package/dialog/package.json

@@ -6,12 +6,5 @@
   "sideEffects": [
     "*.compiled.css"
   ],
-  "types": "../dist/types/entry-points/dialog.d.ts",
-  "typesVersions": {
-    ">=4.5 <5.9": {
-      "*": [
-        "../dist/types-ts4.5/entry-points/dialog.d.ts"
-      ]
-    }
-  }
+  "types": "../dist/types/entry-points/dialog.d.ts"
 }

package/dialog-scroll-lock/package.json

@@ -6,12 +6,5 @@
   "sideEffects": [
     "*.compiled.css"
   ],
-  "types": "../dist/types/entry-points/dialog-scroll-lock.d.ts",
-  "typesVersions": {
-    ">=4.5 <5.9": {
-      "*": [
-        "../dist/types-ts4.5/entry-points/dialog-scroll-lock.d.ts"
-      ]
-    }
-  }
+  "types": "../dist/types/entry-points/dialog-scroll-lock.d.ts"
 }

package/dist/cjs/dialog/dialog-content.js

@@ -57,8 +57,6 @@ var Dialog = exports.Dialog = /*#__PURE__*/(0, _react.forwardRef)(function Dialo
   var dialogId = providedId !== null && providedId !== void 0 ? providedId : generatedId;
   var ownRef = (0, _react.useRef)(null);
   var combinedRef = (0, _mergeRefs.default)([ownRef, ref]);
-
-  // Animation lifecycle
   var _useAnimatedVisibilit = (0, _useAnimatedVisibility.useAnimatedVisibility)({
       isOpen: isOpen,
       animate: animate,
@@ -68,31 +66,22 @@ var Dialog = exports.Dialog = /*#__PURE__*/(0, _react.forwardRef)(function Dialo
     phase = _useAnimatedVisibilit.phase,
     preset = _useAnimatedVisibilit.preset;
 
-  // Pre-computed phase predicate. `isVisible` means "host element is
-  // mounted and on screen" (any phase except `closed`), used as a dep
-  // signal for the backdrop-click rebind effect so it re-attaches to
-  // the fresh <dialog> element after a close → reopen unmount/remount
-  // cycle.
+  // True while the host element is mounted (any phase except `closed`).
+  // Used as a dep so listener-rebind effects re-attach after a remount.
   var isVisible = phase !== 'closed';
 
-  // Focus wrap
-  // Native <dialog>.showModal() traps focus but wraps through <body> at
-  // the boundary (A → B → C → body → A). This hook intercepts Tab to
-  // wrap directly (A → B → C → A), matching the WAI-ARIA APG pattern.
-  //
-  // Takes `phase` directly: the listener stays attached while
-  // `phase !== 'closed'`, i.e. through the animated-exit window.
-  // Gating on `isOpen` would unbind the listener at the start of an
-  // exit animation while the dialog is still visible, letting focus
-  // escape (WCAG 2.4.3 Focus Order regression).
+  // Native `<dialog>.showModal()` traps focus but wraps through `<body>` at
+  // the boundary (A → B → C → body → A). This hook intercepts Tab to wrap
+  // directly (A → B → C → A), matching the WAI-ARIA APG pattern. Passing
+  // `phase` keeps the listener attached through the animated-exit window
+  // (WCAG 2.4.3 Focus Order regression guard).
   (0, _useFocusWrap.useFocusWrap)({
     elementRef: ownRef,
     role: 'dialog',
     phase: phase
   });
 
-  // Open layer observer registration
-  // Notifies the open layer observer so app-coordination features
+  // Notify the open layer observer so app-coordination features
   // (open-count subscriptions) work with top-layer dialogs.
   (0, _openLayerObserver.useNotifyOpenLayerObserver)({
     type: 'modal',
@@ -100,8 +89,6 @@ var Dialog = exports.Dialog = /*#__PURE__*/(0, _react.forwardRef)(function Dialo
     // No-op: no current use case for programmatic close via OpenLayerObserver.
     onClose: _noop.default
   });
-
-  // Show/hide the dialog in response to isOpen changes.
   (0, _react.useLayoutEffect)(function () {
     var dialog = ownRef.current;
     if (!dialog) {
@@ -159,15 +146,10 @@ var Dialog = exports.Dialog = /*#__PURE__*/(0, _react.forwardRef)(function Dialo
   // any atomic class, so the override always wins.
   var escapedId = CSS.escape(dialogId);
 
-  // The `<dialog>` host element is only rendered while open or its exit
-  // animation is playing. After exit completes the phase returns to
-  // `closed` and we unmount the dialog entirely so it does not leave an
-  // empty `role="dialog"` element in the accessibility tree. The element
-  // re-mounts on the next `isOpen=true` commit; `showModal()` is called
-  // from the existing `useLayoutEffect([isOpen])` on that same commit,
-  // and listeners (cancel, click) re-bind via the `[onClose, isVisible]`
-  // effect re-running after remount (React clears the ref on unmount, so
-  // we need the listener effect to re-run with the fresh element).
+  // Unmount the `<dialog>` once exit completes so it does not leave an
+  // empty `role="dialog"` element in the accessibility tree. On the next
+  // open the element remounts and the `[isOpen]` and `[onClose, isVisible]`
+  // effects re-run against the fresh element.
   if (!isVisible) {
     return null;
   }

package/dist/cjs/internal/set-style.js

@@ -9,7 +9,7 @@ exports.setStyle = setStyle;
  * restores the prior inline values (so we do not stomp consumer styles).
  */
 function setStyle(_ref) {
-  var el = _ref.el,
+  var element = _ref.element,
     styles = _ref.styles;
   // Snapshot the prior inline value (NOT the computed style - we only want
   // to restore values that the consumer/our previous run inlined). An empty
@@ -18,23 +18,23 @@ function setStyle(_ref) {
     var property = _ref2.property;
     return {
       property: property,
-      value: el.style.getPropertyValue(property)
+      value: element.style.getPropertyValue(property)
     };
   });
   styles.forEach(function (_ref3) {
     var property = _ref3.property,
       value = _ref3.value;
-    el.style.setProperty(property, value);
+    element.style.setProperty(property, value);
   });
   return function cleanup() {
     priorValues.forEach(function (_ref4) {
       var property = _ref4.property,
         value = _ref4.value;
       if (value === '') {
-        el.style.removeProperty(property);
+        element.style.removeProperty(property);
         return;
       }
-      el.style.setProperty(property, value);
+      element.style.setProperty(property, value);
     });
   };
 }

package/dist/cjs/internal/slot.js

@@ -52,7 +52,7 @@ function isSlotChild(child) {
 var Slot = exports.Slot = /*#__PURE__*/(0, _react.forwardRef)(function Slot(slotProps, ref) {
   var rawChildren = slotProps.children,
     props = (0, _objectWithoutProperties2.default)(slotProps, _excluded);
-  // `SlotProps` intersects `Record<string, unknown>`, so `children` is typed as `unknown`.
+  // `TSlotProps` intersects `Record<string, unknown>`, so `children` is typed as `unknown`.
   var children = rawChildren;
   if (!isSlotChild(children)) {
     return children;

package/dist/cjs/internal/use-anchor-position-at-point.js

@@ -11,7 +11,7 @@ var _useAnchorPosition = require("./use-anchor-position");
  * anchor should be placed.
  *
  * Axis-named (`x`/`y`) rather than edge-named (`left`/`top`) so the
- * shape is unambiguous in RTL writing modes — there is no ambiguity
+ * shape is unambiguous in RTL writing modes - there is no ambiguity
  * about whether a coordinate is logical (`inline-start`/`block-start`)
  * or physical (`left`/`top`). Viewport coordinates are always
  * physical, so we name them with the physical axis labels.
@@ -22,19 +22,19 @@ var _useAnchorPosition = require("./use-anchor-position");
  * Dynamic `inset-*` overrides are written by the positioning effect.
  *
  * Uses `Object.assign` rather than Compiled CSS (element is outside the React tree)
- * or the internal `setStyle` helper (we own this element entirely — it is created
- * and removed by this hook — so the snapshot/restore semantics `setStyle`
+ * or the internal `setStyle` helper (we own this element entirely - it is created
+ * and removed by this hook - so the snapshot/restore semantics `setStyle`
  * provides for caller-owned elements would be dead work here).
  */
-function applyStaticAnchorStyles(el) {
-  Object.assign(el.style, {
+function applyStaticAnchorStyles(element) {
+  Object.assign(element.style, {
     position: 'fixed',
     // `top`/`left` rather than `inset-block-start`/`inset-inline-start`
     // for consistency with the dynamic positioning effect below, which
     // uses physical properties (see comment there for the rationale).
     top: '0',
     left: '0',
-    // Zero size — placement decides which side the popover sits on.
+    // Zero size - placement decides which side the popover sits on.
     width: '0',
     height: '0',
     // Prevent the overlay from intercepting pointer events.
@@ -80,7 +80,7 @@ function useAnchorPositionAtPoint(_ref) {
   var syntheticAnchorRef = (0, _react.useRef)(null);
 
   // `getPoint` is kept in a ref so the layout effect can call the
-  // latest version without listing it as a dep — that would re-fire
+  // latest version without listing it as a dep - that would re-fire
   // on every render and re-latch the point.
   var getPointRef = (0, _react.useRef)(getPoint);
   getPointRef.current = getPoint;
@@ -116,7 +116,7 @@ function useAnchorPositionAtPoint(_ref) {
     };
   }, [isEnabled]);
 
-  // Mirror `isEnabled` so both hooks stay in sync — when disabled,
+  // Mirror `isEnabled` so both hooks stay in sync - when disabled,
   // neither this hook nor the inner one touches the popover, leaving
   // any other positioning the consumer has set up free to take effect.
   (0, _useAnchorPosition.useAnchorPosition)({

package/dist/cjs/internal/use-anchor-position.js

@@ -152,17 +152,11 @@ function crossAxisShiftMargin(_ref2) {
 }
 
 /**
- * Returns a referentially-stable, fully-resolved `TPlacement`. `useMemo` is
- * keyed on the primitive fields of the input so a fresh inline `placement`
- * object on every render does not produce a fresh resolved object. Both
- * `getPlacement` and the equality check are skipped when the inputs are
- * unchanged.
+ * Returns a referentially-stable, fully-resolved `TPlacement`. The memo is
+ * keyed on the resolved primitive fields so a fresh inline `placement` object
+ * (or undefined fields vs explicit defaults) does not produce a fresh result.
  */
 function useStablePlacement(placement) {
-  // Resolve to the fully-defaulted primitives BEFORE the memo so the deps
-  // array sees the same key for `{}`, `undefined` fields, and explicit
-  // defaults. Otherwise `axis: undefined` and `axis: 'block'` would be
-  // treated as different inputs and re-run the downstream effect.
   var resolved = (0, _resolvePlacement.getPlacement)({
     placement: placement
   });
@@ -172,10 +166,8 @@ function useStablePlacement(placement) {
   var gap = resolved.offset.gap;
   var shiftValue = resolved.offset.crossAxisShift.value;
   var shiftDirection = resolved.offset.crossAxisShift.direction;
-  // Rebuild the placement object inside the memo from the resolved primitive
-  // deps so the factory does not close over the (potentially fresh) outer
-  // `resolved` reference, and `react-hooks/exhaustive-deps` can verify the
-  // deps array.
+  // Rebuild inside the memo from primitive deps so the factory does not
+  // close over the outer `resolved` reference and exhaustive-deps can verify.
   return (0, _react.useMemo)(function () {
     return {
       axis: axis,
@@ -207,10 +199,6 @@ function useStablePlacement(placement) {
  * When not supported, it falls back to JavaScript-based positioning using
  * `position: fixed` with measured coordinates, re-running on scroll (capture)
  * and resize events.
- *
- * `placement` may be a fresh inline object on every render: a structural
- * comparison is used internally so re-runs are skipped when the resolved
- * placement shape is unchanged.
  */
 // eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 function useAnchorPosition(_ref3) {
@@ -224,8 +212,6 @@ function useAnchorPosition(_ref3) {
     isEnabled = _ref3$isEnabled === void 0 ? true : _ref3$isEnabled,
     isOpen = _ref3.isOpen;
   var id = (0, _react.useId)();
-  // Stabilize `placement` object so the same object literal
-  // value returns an object with the same reference
   var stablePlacement = useStablePlacement(placement);
   (0, _react.useLayoutEffect)(function () {
     if (!isEnabled) {
@@ -247,9 +233,9 @@ function useAnchorPosition(_ref3) {
         placement: stablePlacement,
         offset: gapCssValue
       });
-      // Hoist crossAxisShift to a single computation; reused below to
-      // populate the active `--ds-cross-axis-shift-margin-*` custom
-      // property for the named arrow @position-try rules.
+      // Computed once; reused below to populate the active
+      // `--ds-cross-axis-shift-margin-*` custom property for the
+      // named arrow @position-try rules.
       var crossAxisShift = crossAxisShiftMargin({
         placement: stablePlacement,
         crossAxisShiftCssValue: crossAxisShiftCssValue,
@@ -277,22 +263,17 @@ function useAnchorPosition(_ref3) {
       }, {
         property: 'inset',
         value: 'auto'
-      },
-      // Main-axis gap between the popover and its trigger
-      {
+      }, {
         property: gap.property,
         value: gap.value
-      },
-      // Cross-axis shift
-      {
+      }, {
         property: crossAxisShift.property,
         value: crossAxisShift.value
       }];
 
-      // Surface the active cross-axis shift value as a custom property so
-      // each named arrow @position-try rule can re-apply it after a flip.
-      // The four properties cover (cross-axis, side); only one is non-zero
-      // at a time.
+      // Expose the active cross-axis shift via custom properties so each
+      // named arrow @position-try rule can re-apply it after a flip.
+      // One of the four (cross-axis, side) properties is non-zero at a time.
       popoverStyles.push({
         property: '--ds-cross-axis-shift-margin-start',
         value: '0px'
@@ -309,9 +290,8 @@ function useAnchorPosition(_ref3) {
         property: '--ds-cross-axis-shift-margin-block-end',
         value: '0px'
       });
-      // `crossAxisShift` IS the active margin - reuse instead of recomputing.
+      // `crossAxisShift` IS the active margin; reuse instead of recomputing.
       var crossAxisShiftActive = crossAxisShift;
-      // Map margin property to its corresponding custom property name.
       var customPropertyByMarginProperty = {
         'margin-inline-start': '--ds-cross-axis-shift-margin-start',
         'margin-inline-end': '--ds-cross-axis-shift-margin-end',
@@ -345,18 +325,17 @@ function useAnchorPosition(_ref3) {
        */
       trigger.style.setProperty('anchor-name', anchorName);
       var _undoPositioning = (0, _combine.combine)((0, _setStyle.setStyle)({
-        el: popover,
+        element: popover,
         styles: popoverStyles
       }));
       return _undoPositioning;
     }
 
-    // JS fallback
-    // The popover is already in the browser's top layer via popover="auto",
-    // so it does not need position:fixed. We only reset the UA defaults
-    // (inset: 0; margin: auto) and set top/left based on measurements.
+    // JS fallback. The popover is already in the top layer via
+    // popover="auto", so we only reset UA defaults and set top/left
+    // based on measurements.
     var cleanupBaseStyles = (0, _setStyle.setStyle)({
-      el: popover,
+      element: popover,
       styles: [{
         property: 'margin',
         value: '0'