@protonradio/proton-ui 0.1.42 → 0.2.0

package/README.md

@@ -1,64 +1,50 @@
-# Proton UI
-
-![](./.readme.gif)
-
-```
-npm run storybook
-```
-
-### Publishing Updates to NPM
-```
-npm run build
-npm version <new_version>  // increment version in package.json accordingly using semver
-npm publish
-```
-
-### Themes
-This library supports themes for the various applications that use it. Ideally, we would unify our app designs, but until then themes is a way to support different design patterns using the same api.
-
-#### Adding a Theme
-The current supported themes can be found in the `src/themes/config.ts`. To add a new theme, create a new attribute on the `THEME_CONFIG` object following the pattern `[themeName]: [themeClassName]`.
-
-When applying to a project, you can import available themes using `THEME_CONFIG` from this library and apply the theme an outer div on the application. See below for an example.
-
-```jsx
-import { THEME_CONFIG } from '@protonradio/proton-ui'
-
-function MyApp({ Component, pageProps }) {
-  return (
-    <div className={THEME_CONFIG.ReleaseLinks}> {/* Set your theme here */}
-      <Component {...pageProps} />
-    </div>
-  );
-}
-```
-
-#### Styling for a theme
-To apply theme specific styles in a component, you can select using the class name that belongs to the theme (see `src/themes/config.ts`). For example, to apply a style to the `ReleaseLinks` theme, you can use the following css.
-
-Theme specific css should be placed in the `src/themes` directory in a unqiue file for the theme and component. The file naming convention should be `[componentName].[themeClassName].css`.
-
-```css
-.ReleaseLinks .myComponent {
-  background-color: red;
-}
-```
-
-#### Overriding CSS Variables
-Components reuse common colors across components and, in an attempt to unify these colors under common variables, common component attributes have been defined in globals.css and can be overridden at the theme level (ex: src/themes/release-links/index.css`.
-
-These should be used where possible so that if we decide to change styling accross the component library we can do so in just a few places.
-
-This also makes it easier for overriding some component styles from within a project to something more dynamic. In the case of the `ReleaseLinks` app, we calculate some background colors from the album artwork. Because of this we want to override the background color of certain elements in the `ReleaseLinks` theme with a css variable.
-
-An example of this might look like:
-
-```js
-document.documentElement.style.setProperty(
-  "--proton-control-background",
-  buttonBackgroundColor
-);
-```
-
-### Recommended Reading
-- https://www.gabe.pizza/notes-on-component-libraries/
+# Proton UI
+
+![](./.readme.gif)
+
+```
+npm run storybook
+```
+
+### Publishing Updates to NPM
+
+```
+npm run build
+npm version <new_version>  // increment version in package.json accordingly using semver
+npm publish
+```
+
+### Themes
+
+This library supports themes for the various applications that use it. Ideally, we would unify our app designs, but until then themes is a way to support different design patterns using the same api.
+
+#### Adding a Theme
+
+The current supported themes can be found in the `src/themes/config.ts`. To add a new theme, create a new attribute on the `THEMES` object following the pattern `[themeName]: [themeClassName]`.
+
+When applying to a project, you can import available themes using `THEMES` from this library and apply the theme an outer div on the application. See below for an example.
+
+```jsx
+function MyApp({ Component, pageProps }) {
+  return (
+    <ThemeProvider theme={THEMES.DARK}>
+      <Component {...pageProps} />
+    </ThemeProvider>
+  );
+}
+```
+
+#### Styling for a theme
+
+To apply theme specific styles in a component, we set theme specific css variables in the `src/themes/config.ts` file, in `generateThemeCssVariables` function. If you need more control, you can add either use the `useTheme` hook to manipulate the DOM, or you can use css selectors that reference the wrapping theme class.
+
+For example, to apply a style to the dark theme, you can use the following css.
+```css
+.proton-ui__theme--dark .myComponent {
+  background-color: red;
+}
+```
+
+### Recommended Reading
+
+- https://www.gabe.pizza/notes-on-component-libraries/

package/dist/icons.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+  <defs>
+    <symbol id="external-link" viewBox="0 0 512 512">
+      <path d="M384 224v184a40 40 0 01-40 40H104a40 40 0 01-40-40V168a40 40 0 0140-40h167.48M336 64h112v112M224 288L440 72" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="32"/>
+    </symbol>
+
+    <symbol id="caret-down" viewBox="0 0 512 512">
+      <path fill="currentColor" d="M233.4 406.6c12.5 12.5 32.8 12.5 45.3 0l192-192c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L256 338.7L86.6 169.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l192 192z"/>
+    </symbol>
+  </defs>
+</svg>

package/dist/proton-ui.es.d.ts

@@ -1,16 +1,21 @@
-import type { AriaDialogProps } from 'react-aria';
+import { AriaDialogProps } from 'react-aria';
 import type { AriaPopoverProps } from 'react-aria';
 import { AriaSelectProps } from 'react-aria';
+import { AriaTableProps } from 'react-aria';
 import { ColumnProps } from '@react-stately/table';
 import { JSX as JSX_2 } from 'react/jsx-runtime';
 import { OverlayTriggerProps } from 'react-stately';
 import { OverlayTriggerState } from 'react-stately';
 import { PressEvent } from 'react-aria';
 import { default as React_2 } from 'react';
+import { ReactNode } from 'react';
 import { Row } from '@react-stately/table';
 import { Section } from '@react-stately/table';
 import { TableBody } from '@react-stately/table';
 import { TableHeader } from '@react-stately/table';
+import { TableStateProps } from 'react-stately';
+import { TooltipProps as TooltipProps_2 } from 'react-aria-components';
+import { TooltipTriggerComponentProps } from 'react-aria-components';
 
 export declare function Button(props: ButtonProps): JSX_2.Element;
 
@@ -62,7 +67,7 @@ declare interface ButtonProps {
     /**
      * The button's visual aesthetic.
      */
-    variant?: "primary" | "secondary" | "danger" | "rl-primary";
+    variant?: "primary" | "secondary" | "danger";
     /**
      * Should the button be non-interactive?
      */
@@ -79,10 +84,6 @@ declare interface ButtonProps {
      * The content to display within the button.
      */
     children?: React.ReactNode;
-    /**
-     * Optionally pass a custom ref to the button.
-     */
-    buttonRef?: React.MutableRefObject<any>;
 }
 
 export declare const Cell: <T>(props: ProtonColumnProps<T>) => JSX_2.Element;
@@ -99,9 +100,13 @@ declare interface DialogProps extends AriaDialogProps {
     children: React.ReactNode;
 }
 
-export declare function Icon(props: IconProps): JSX_2.Element;
+export declare const generateThemeCssVariables: (baseColor: RGBArray | null) => Record<Theme, ThemeVariables>;
+
+export declare const generateThemedRGBArray: (baseColor: RGBArray | null) => RGBArray;
+
+export declare function Icon(props: Omit<IconProps, "svgContent">): JSX_2.Element;
 
-declare type IconID = "external-link" | "caret-down" | "chevron-down";
+declare type IconID = "external-link" | "caret-down";
 
 declare interface IconProps {
     /**
@@ -123,6 +128,9 @@ export declare function Popover({ children, state, arrow, offset, ...props }: Po
 /**
  * Popover is an unstyled popover component that handles positioning. It should be used
  * with the Dialog component to provide a styled popover.
+ *
+ * A popover displays interactive content in context with a trigger element.
+ * A tooltip displays a description of an element on hover or focus.
  */
 declare interface PopoverProps extends Omit<AriaPopoverProps, "popoverRef"> {
     /**
@@ -147,6 +155,8 @@ export declare interface ProtonColumnProps<T> extends ColumnProps<T> {
     align?: "left" | "center" | "right";
 }
 
+export declare type RGBArray = [number, number, number];
+
 export { Row }
 
 export { Section }
@@ -156,7 +166,7 @@ export declare const Select: {
     Option: any;
 };
 
-declare function SelectMenu<T extends object>(props: SelectProps<T>): JSX_2.Element;
+declare function SelectMenu<T extends object>({ label, name, isDisabled, ...props }: SelectProps<T>): JSX_2.Element;
 
 declare interface SelectProps<T> extends AriaSelectProps<T> {
     label?: string;
@@ -200,17 +210,71 @@ declare interface SwitchProps {
     children?: React.ReactNode;
 }
 
-export declare function Table(props: any): JSX_2.Element;
+export declare function Table(props: TableProps): JSX_2.Element;
 
 export { TableBody }
 
 export { TableHeader }
 
-export declare const THEME_CONFIG: {
-    readonly ReleaseLinks: "rl-theme";
-    readonly ProtonRadio: "client-theme";
+declare type TableProps = AriaTableProps & TableStateProps<object>;
+
+export declare type Theme = (typeof THEMES)[keyof typeof THEMES];
+
+export declare const THEME_CLASSES: {
+    dark: string;
+    light: string;
+};
+
+declare interface ThemeContextType {
+    theme: Theme;
+    className: string;
+    style: ReturnType<typeof generateThemeCssVariables>[Theme];
+    baseColor: RGBArray;
+    themedRGBArray: RGBArray;
+}
+
+export declare const ThemeProvider: React_2.FC<ThemeProviderProps>;
+
+declare interface ThemeProviderProps {
+    theme: Theme;
+    children: ReactNode;
+    baseColor?: RGBArray;
+}
+
+export declare const THEMES: {
+    readonly DARK: "dark";
+    readonly LIGHT: "light";
 };
 
+export declare interface ThemeVariables {
+    "--proton-control-background": string;
+    "--proton-text-color": string;
+    "--proton-control-border": string;
+}
+
+export declare function Tooltip({ children, arrow, ...props }: TooltipProps): JSX_2.Element;
+
+export declare interface TooltipProps extends Omit<TooltipProps_2, "children"> {
+    children: React.ReactNode;
+    arrow?: boolean;
+}
+
+/**
+ * Proton's TooltipTrigger component deviates from the Aria TooltipTrigger in that on mobile,
+ * the trigger also opens the tooltip on click as well as hover & focus. This is to improve
+ * accessibility and usability on mobile.
+ *
+ * If you wish to disable the trigger click feature, you can set the `disableTriggerClick` prop.
+ * This is useful when using an info only Tooltip that might wrap a clickable element.
+ */
+export declare function TooltipTrigger({ children, delay, closeDelay, isDisabled, defaultOpen, onOpenChange, disableTriggerClick, content, ...tooltipProps }: TooltipTriggerProps): JSX_2.Element;
+
+declare interface TooltipTriggerProps extends TooltipProps, TooltipTriggerComponentProps {
+    children: React.ReactNode;
+    content: string;
+    disableTriggerClick?: boolean;
+}
+
 /**
  * Hook for creating a popover trigger. This hook manages the state and events for the popover
  * and popover trigger. For examples see Popover.stories.tsx.
@@ -222,4 +286,6 @@ export declare function usePopoverTrigger(props?: OverlayTriggerProps): {
     state: any;
 };
 
+export declare const useTheme: () => ThemeContextType;
+
 export { }