@openedx/paragon 23.0.0-alpha.2 → 23.0.0-alpha.3

package/src/index.js

@@ -1,13 +1,18 @@
-// To keep this file in sync with the .d.ts file, it's in the same order
-// and each line number is the same
+// Keep this file in sync with the .d.ts file (manually). It's in the same order
+// and each line number is the same, to make it easier.
 
 // // // // // // // // // // // // // // // // // // // // // // // // // // //
 // Things that have types
 // // // // // // // // // // // // // // // // // // // // // // // // // // //
 export { default as Bubble } from './Bubble';
+export { default as Button, ButtonGroup, ButtonToolbar } from './Button';
 export { default as Chip, CHIP_PGN_CLASS } from './Chip';
 export { default as ChipCarousel } from './ChipCarousel';
+export { default as Hyperlink, HYPER_LINK_EXTERNAL_LINK_ALT_TEXT, HYPER_LINK_EXTERNAL_LINK_TITLE } from './Hyperlink';
 export { default as Icon } from './Icon';
+export { default as IconButton, IconButtonWithTooltip } from './IconButton';
+export { default as Overlay, OverlayTrigger } from './Overlay';
+export { default as Tooltip } from './Tooltip';
 
 // // // // // // // // // // // // // // // // // // // // // // // // // // //
 // Things that don't have types
@@ -20,7 +25,6 @@ export { default as Avatar } from './Avatar';
 export { default as AvatarButton } from './AvatarButton';
 export { default as Badge } from './Badge';
 export { default as Breadcrumb } from './Breadcrumb';
-export { default as Button, ButtonGroup, ButtonToolbar } from './Button';
 export {
   default as Card,
   CardColumns,
@@ -69,8 +73,6 @@ export {
   FormAutosuggestOption,
   InputGroup,
 } from './Form';
-export { default as Hyperlink, HYPER_LINK_EXTERNAL_LINK_ALT_TEXT, HYPER_LINK_EXTERNAL_LINK_TITLE } from './Hyperlink';
-export { default as IconButton, IconButtonWithTooltip } from './IconButton';
 export { default as IconButtonToggle } from './IconButtonToggle';
 export { default as Image, Figure } from './Image';
 export { default as MailtoLink, MAIL_TO_LINK_EXTERNAL_LINK_ALTERNATIVE_TEXT, MAIL_TO_LINK_EXTERNAL_LINK_TITLE } from './MailtoLink';
@@ -97,7 +99,6 @@ export {
   NavLink,
 } from './Nav';
 export { default as Navbar, NavbarBrand, NAVBAR_LABEL } from './Navbar';
-export { default as Overlay, OverlayTrigger } from './Overlay';
 export { default as PageBanner, PAGE_BANNER_DISMISS_ALT_TEXT } from './PageBanner';
 export {
   default as Pagination,
@@ -132,7 +133,6 @@ export {
   TabPane,
 } from './Tabs';
 export { default as Toast, TOAST_CLOSE_LABEL_TEXT, TOAST_DELAY } from './Toast';
-export { default as Tooltip } from './Tooltip';
 export { default as TransitionReplace } from './TransitionReplace';
 export { default as ValidationMessage } from './ValidationMessage';
 export { default as DataTable } from './DataTable';

package/src/{setupTest.js → setupTest.ts}

@@ -1,3 +1,4 @@
+/* eslint-disable import/no-extraneous-dependencies */
 import 'regenerator-runtime/runtime';
 
 import '@testing-library/jest-dom';

package/src/utils/types/bootstrap.test.tsx

@@ -0,0 +1,86 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import React from 'react';
+import type { BsPropsWithAs, ComponentWithAsProp } from './bootstrap';
+
+// Note: these are type-only tests. They don't actually do much at runtime; the important checks are at transpile time.
+
+describe('BsPropsWithAs', () => {
+  interface Props<As extends React.ElementType = 'table'> extends BsPropsWithAs<As> {
+    otherProp?: number;
+  }
+
+  it('defines optional bsPrefix, className, and as but no other props', () => {
+    const checkProps = <As extends React.ElementType = 'table'>(_props: Props<As>) => {};
+    // These are all valid props per the prop definition:
+    checkProps({ });
+    checkProps({ bsPrefix: 'bs' });
+    checkProps({ className: 'foo bar' });
+    checkProps({ as: 'tr' });
+    checkProps({ className: 'foo bar', as: 'button', otherProp: 15 });
+    // But these are all invalid:
+    // @ts-expect-error
+    checkProps({ newProp: 10 });
+    // @ts-expect-error
+    checkProps({ onClick: () => {} });
+    // @ts-expect-error
+    checkProps({ id: 'id' });
+    // @ts-expect-error
+    checkProps({ children: <tr /> });
+  });
+});
+
+describe('ComponentWithAsProp', () => {
+  interface MyProps extends BsPropsWithAs {
+    customProp?: string;
+  }
+  const MyComponent: ComponentWithAsProp<'div', MyProps> = (
+    React.forwardRef<HTMLDivElement, MyProps>(
+      ({ as: Inner = 'div', ...props }, ref) => <Inner {...props} ref={ref} />,
+    )
+  );
+
+  // eslint-disable-next-line react/function-component-definition
+  const CustomComponent: React.FC<{ requiredProp: string }> = () => <span />;
+
+  it('is defined to wrap a <div> by default, and accepts related props', () => {
+    // This is valid - by default it is a DIV so accepts props and ref related to DIV:
+    const divClick: React.MouseEventHandler<HTMLDivElement> = () => {};
+    const divRef: React.RefObject<HTMLDivElement> = { current: null };
+    const valid = <MyComponent ref={divRef} onClick={divClick} customProp="foo" />;
+  });
+
+  it('is defined to wrap a <div> by default, and rejects unrelated props', () => {
+    const btnRef: React.RefObject<HTMLButtonElement> = { current: null };
+    // @ts-expect-error because the ref is to a <button> ref, but this is wrapping a <div>
+    const invalidRef = <MyComponent ref={btnRef} customProp="foo" />;
+
+    const btnClick: React.MouseEventHandler<HTMLButtonElement> = () => {};
+    // @ts-expect-error because the handler is for a <button> event, but this is wrapping a <div>
+    const invalidClick = <MyComponent onClick={btnClick} />;
+  });
+
+  it('can be changed to wrap a <canvas>, and accepts related props', () => {
+    const canvasClick: React.MouseEventHandler<HTMLCanvasElement> = () => {};
+    const canvasRef: React.RefObject<HTMLCanvasElement> = { current: null };
+    const valid = <MyComponent as="canvas" ref={canvasRef} onClick={canvasClick} customProp="foo" />;
+  });
+
+  it('can be changed to wrap a <canvas>, and rejects unrelated props', () => {
+    const btnRef: React.RefObject<HTMLButtonElement> = { current: null };
+    // @ts-expect-error because the ref is to a <button> ref, but this is wrapping an <canvas>
+    const invalidRef = <MyComponent as="canvas" ref={btnRef} customProp="foo" />;
+
+    const btnClick: React.MouseEventHandler<HTMLButtonElement> = () => {};
+    // @ts-expect-error because the handler is for a <button> event, but this is wrapping an <canvas>
+    const invalidClick = <MyComponent as="canvas" onClick={btnClick} />;
+  });
+
+  it('can be changed to wrap a custom component, and accepts related props', () => {
+    const valid = <MyComponent as={CustomComponent} requiredProp="hello" />;
+  });
+
+  it('can be changed to wrap a custom component, and rejects unrelated props', () => {
+    // @ts-expect-error The onClick prop has not been declared for our custom component.
+    const valid = <MyComponent as={CustomComponent} requiredProp="hello" onClick={() => {}} />;
+  });
+});

package/src/utils/types/bootstrap.ts

@@ -0,0 +1,43 @@
+/**
+ * Types related to bootstrap components
+ */
+import React from 'react';
+
+import type { BsPrefixProps, BsPrefixRefForwardingComponent } from 'react-bootstrap/esm/helpers';
+
+/**
+ * Type helper for defining props of a component that wraps a bootstrap
+ * component. This type defines three props:
+ *    1. `className`: this component accepts additional CSS classes.
+ *    2. `bsPrefix`: locally change the class name prefix used for this component.
+ *    3. `as`: optionally specify which HTML element or Component is used, e.g. `"div"`
+ *
+ * This type assumes no `children` are allowed, but you can extend it to allow children.
+ */
+export type BsPropsWithAs<As extends React.ElementType = React.ElementType> = BsPrefixProps<As>;
+
+/**
+ * This is a helper that can be used to define the type of a Paragon component
+ * that accepts an `as` prop.
+ *
+ * It:
+ *   - assumes you are using `forwardRef`, and sets the type of the `ref` prop
+ *     to match the type of the component passed in the `as` prop.
+ *   - assumes you are passing all unused props to the component, so adds any
+ *     props from the `as` component type to the props you specify as `Props`.
+ *
+ * Example;
+ * ```
+ * interface MyProps extends BsPropsWithAs {
+ *   customProp?: string;
+ * }
+ * export const MyComponent: ComponentWithAsProp<'div', MyProps> = (
+ *   React.forwardRef<HTMLDivElement, MyProps>(
+ *     ({ as: Inner = 'div', ...props }, ref) => <Inner {...props} ref={ref} />,
+ *   )
+ * );
+ * ```
+ * Note that you need to define the default (e.g. `'div'`) in three different places.
+ */
+export type ComponentWithAsProp<DefaultElementType extends React.ElementType, Props>
+  = BsPrefixRefForwardingComponent<DefaultElementType, Props>;

package/src/IconButton/__snapshots__/IconButton.test.jsx.snap

@@ -1,20 +0,0 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
-
-exports[`<IconButton /> renders with required props 1`] = `
-<button
-  aria-label="alternative"
-  className="btn-icon btn-icon-primary btn-icon-md"
-  onClick={[Function]}
-  type="button"
->
-  <span
-    className="btn-icon__icon-container"
-  >
-    <span
-      aria-hidden={true}
-      className="btn-icon__icon"
-      id="Icon1"
-    />
-  </span>
-</button>
-`;