@apify/ui-library 1.152.2 → 1.152.4-featureexposetestids-bd5e63.21

package/dist/type_utils.d.ts

@@ -1,6 +1,28 @@
+import { ComponentPropsWithRef, ComponentPropsWithoutRef, ElementType, ReactNode } from 'react';
 export type WithTransientProps<T> = {
     [P in keyof T & string as `$${P}`]: T[P];
 };
 export type WithRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
 export type WithOptional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
+/**
+ * Polymorphic component typing helpers (Pattern B) for the `as`-prop pattern in the
+ * UI Component Typing RFC. Only for components that switch their element via `as`;
+ * others extend `React.ComponentPropsWithoutRef<'element'>` directly (Pattern A).
+ */
+/** Ref type for element `E`. Conditional `infer`, not `ComponentPropsWithRef<E>['ref']` — indexed access widens to `unknown` for an unbound generic `E`. */
+export type PolymorphicRef<E extends ElementType> = ComponentPropsWithRef<E> extends {
+    ref?: infer R;
+} ? R : never;
+/** `OwnProps` plus the shared `as` and `children`. */
+type PolymorphicOwnProps<E extends ElementType, OwnProps extends object = object> = OwnProps & {
+    as?: E;
+    children?: ReactNode;
+};
+/** Own props + element `E`'s HTML attributes. Own props win via `Omit` (they replace, not merge with, native typing). */
+export type PolymorphicComponentProps<E extends ElementType, OwnProps extends object = object> = PolymorphicOwnProps<E, OwnProps> & Omit<ComponentPropsWithoutRef<E>, keyof PolymorphicOwnProps<E, OwnProps>>;
+/** Adds a `ref` typed for element `E` (React 19: `ref` is a regular prop, no `forwardRef`). */
+export type PolymorphicComponentPropsWithRef<E extends ElementType, OwnProps extends object = object> = PolymorphicComponentProps<E, OwnProps> & {
+    ref?: PolymorphicRef<E>;
+};
+export {};
 //# sourceMappingURL=type_utils.d.ts.map

package/dist/type_utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"type_utils.d.ts","sourceRoot":"","sources":["../src/type_utils.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAEjF,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAC1E,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC"}
+{"version":3,"file":"type_utils.d.ts","sourceRoot":"","sources":["../src/type_utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKrG,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,IAAI,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AAEjF,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAC1E,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAElF;;;;GAIG;AAEH,4JAA4J;AAC5J,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,WAAW,IAAI,qBAAqB,CAAC,CAAC,CAAC,SAAS;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,KAAK,CAAC;AAEnH,sDAAsD;AACtD,KAAK,mBAAmB,CAAC,CAAC,SAAS,WAAW,EAAE,QAAQ,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,GAAG;IAC3F,EAAE,CAAC,EAAE,CAAC,CAAC;IACP,QAAQ,CAAC,EAAE,SAAS,CAAC;CACxB,CAAC;AAEF,yHAAyH;AACzH,MAAM,MAAM,yBAAyB,CAAC,CAAC,SAAS,WAAW,EAAE,QAAQ,SAAS,MAAM,GAAG,MAAM,IAAI,mBAAmB,CAChH,CAAC,EACD,QAAQ,CACX,GACG,IAAI,CAAC,wBAAwB,CAAC,CAAC,CAAC,EAAE,MAAM,mBAAmB,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE9E,+FAA+F;AAC/F,MAAM,MAAM,gCAAgC,CACxC,CAAC,SAAS,WAAW,EACrB,QAAQ,SAAS,MAAM,GAAG,MAAM,IAChC,yBAAyB,CAAC,CAAC,EAAE,QAAQ,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC"}

package/dist/type_utils.type-test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=type_utils.type-test.d.ts.map

package/dist/type_utils.type-test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type_utils.type-test.d.ts","sourceRoot":"","sources":["../src/type_utils.type-test.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,12 +1,24 @@
 {
     "name": "@apify/ui-library",
-    "version": "1.152.2",
+    "version": "1.152.4-featureexposetestids-bd5e63.21+3b6bb4035a8",
     "description": "React UI library used by apify.com",
     "license": "Apache-2.0",
     "type": "module",
     "sideEffects": false,
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./test-ids": {
+            "types": "./dist/test_ids.d.ts",
+            "default": "./dist/test_ids.js"
+        },
+        "./style/*": "./style/*",
+        "./package.json": "./package.json"
+    },
     "publishConfig": {
         "registry": "https://registry.npmjs.org",
         "access": "public"
@@ -63,7 +75,7 @@
         "styled-components": "^6.1.19"
     },
     "devDependencies": {
-        "@apify-packages/types": "^3.390.2",
+        "@apify-packages/types": "^3.391.0",
         "@storybook/react-vite": "^10.3.5",
         "@testing-library/react": "^16.3.2",
         "@types/hast": "^3.0.4",
@@ -83,5 +95,5 @@
         "src",
         "style"
     ],
-    "gitHead": "0f5476cbf11d984ceb7ff6c6f6b61932a06d1490"
+    "gitHead": "3b6bb4035a8667c17b58dcedf67b7069905806f8"
 }

package/src/components/shortcut/shortcut.tsx

@@ -1,16 +1,18 @@
-import type { ElementType } from 'react';
+import type { ElementType, ReactNode } from 'react';
 import styled, { css } from 'styled-components';
 
 import { theme } from '../../design_system/theme';
+import type { PolymorphicComponentProps } from '../../type_utils';
 import { Text } from '../text';
 
-interface ShortcutProps {
-    as?: ElementType;
-    className?: string;
-    children: React.ReactNode;
-    /* If true, always use dark mode colors */
+type ShortcutOwnProps = {
+    /** Always use dark-mode colors (e.g. inside tooltips). */
     dark?: boolean;
-}
+    children: ReactNode;
+};
+
+// Pattern B (polymorphic `as`). No ref forwarded (wraps `Text`) → WithoutRef variant (RFC Q3).
+export type ShortcutProps<E extends ElementType = 'span'> = PolymorphicComponentProps<E, ShortcutOwnProps>;
 
 const adaptiveColors = css`
     background-color: ${theme.color.neutral.backgroundSubtle};
@@ -36,10 +38,8 @@ const StyledShortcut = styled(Text)<{ $dark?: boolean }>`
     ${({ $dark }) => ($dark ? darkColors : adaptiveColors)}
 `;
 
-export const Shortcut = ({ as, className, children, dark = false }: ShortcutProps) => {
-    return (
-        <StyledShortcut forwardedAs={as} className={className} $dark={dark} type="code" size="small" weight="medium">
-            {children}
-        </StyledShortcut>
-    );
-};
+export const Shortcut = <E extends ElementType = 'span'>({ as, children, dark = false, ...rest }: ShortcutProps<E>) => (
+    <StyledShortcut forwardedAs={as} $dark={dark} type="code" size="small" weight="medium" {...rest}>
+        {children}
+    </StyledShortcut>
+);

package/src/test_ids.ts

@@ -0,0 +1,5 @@
+// Aggregates every `*.test_ids.ts` module in this package behind the `./test-ids`
+// subpath export. Consumers (notably Playwright specs) import test IDs from here to
+// avoid pulling the React/CSS-heavy root barrel, which breaks non-bundler loaders.
+// Add future test ID modules to this barrel.
+export { tableTestIds } from './components/table/table.test_ids.js';

package/src/type_utils.ts

@@ -1,3 +1,5 @@
+import type { ComponentPropsWithRef, ComponentPropsWithoutRef, ElementType, ReactNode } from 'react';
+
 // This utility will add $ at the beginning of the each interface prop
 // We do that in order to tell styled component to not propagate the given prop down to the dom element
 // It's called transient props (https://styled-components.com/docs/api#transient-props)
@@ -5,3 +7,31 @@ export type WithTransientProps<T> = { [P in keyof T & string as `$${P}`]: T[P] }
 
 export type WithRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
 export type WithOptional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
+
+/**
+ * Polymorphic component typing helpers (Pattern B) for the `as`-prop pattern in the
+ * UI Component Typing RFC. Only for components that switch their element via `as`;
+ * others extend `React.ComponentPropsWithoutRef<'element'>` directly (Pattern A).
+ */
+
+/** Ref type for element `E`. Conditional `infer`, not `ComponentPropsWithRef<E>['ref']` — indexed access widens to `unknown` for an unbound generic `E`. */
+export type PolymorphicRef<E extends ElementType> = ComponentPropsWithRef<E> extends { ref?: infer R } ? R : never;
+
+/** `OwnProps` plus the shared `as` and `children`. */
+type PolymorphicOwnProps<E extends ElementType, OwnProps extends object = object> = OwnProps & {
+    as?: E;
+    children?: ReactNode;
+};
+
+/** Own props + element `E`'s HTML attributes. Own props win via `Omit` (they replace, not merge with, native typing). */
+export type PolymorphicComponentProps<E extends ElementType, OwnProps extends object = object> = PolymorphicOwnProps<
+    E,
+    OwnProps
+> &
+    Omit<ComponentPropsWithoutRef<E>, keyof PolymorphicOwnProps<E, OwnProps>>;
+
+/** Adds a `ref` typed for element `E` (React 19: `ref` is a regular prop, no `forwardRef`). */
+export type PolymorphicComponentPropsWithRef<
+    E extends ElementType,
+    OwnProps extends object = object,
+> = PolymorphicComponentProps<E, OwnProps> & { ref?: PolymorphicRef<E> };

package/src/type_utils.type-test.ts

@@ -0,0 +1,35 @@
+/**
+ * Type-level tests for the polymorphic helpers in `type_utils.ts`, using vitest's built-in
+ * `expectTypeOf` (no extra dependency). No runtime assertions — mismatches surface as `tsc`
+ * errors, so the existing `type-check` script enforces them. Named `.type-test.ts` (not
+ * `.test.ts`) so `vitest run` skips it and Vite leaves it out of the build.
+ */
+import { expectTypeOf } from 'vitest';
+
+import type { PolymorphicComponentProps, PolymorphicComponentPropsWithRef, PolymorphicRef } from './type_utils';
+
+type OwnProps = { variant?: 'a' | 'b' };
+type CustomClick = { onClick: (value: number) => void };
+
+// `as` is typed to the element parameter.
+expectTypeOf<PolymorphicComponentProps<'a'>['as']>().toEqualTypeOf<'a' | undefined>();
+
+// Element-specific native attributes are present and narrow with `as`.
+expectTypeOf<PolymorphicComponentProps<'a'>>().toHaveProperty('href');
+expectTypeOf<PolymorphicComponentProps<'button'>>().toHaveProperty('type');
+expectTypeOf<PolymorphicComponentProps<'button'>>().not.toHaveProperty('href');
+
+// Common attributes are always present regardless of element.
+expectTypeOf<PolymorphicComponentProps<'div'>>().toHaveProperty('aria-label');
+expectTypeOf<PolymorphicComponentProps<'div'>>().toHaveProperty('tabIndex');
+
+// Own props merge in and win over native ones via `Omit`.
+expectTypeOf<PolymorphicComponentProps<'div', OwnProps>['variant']>().toEqualTypeOf<'a' | 'b' | undefined>();
+expectTypeOf<PolymorphicComponentProps<'button', CustomClick>['onClick']>().toEqualTypeOf<(value: number) => void>();
+
+// The WithRef variant adds `ref`; the plain variant does not.
+expectTypeOf<PolymorphicComponentPropsWithRef<'div'>>().toHaveProperty('ref');
+expectTypeOf<PolymorphicComponentProps<'div'>>().not.toHaveProperty('ref');
+
+// `PolymorphicRef` resolves to a concrete (non-`never`) ref type for a bound element.
+expectTypeOf<PolymorphicRef<'a'>>().not.toBeNever();