@protonradio/proton-ui 0.11.0-beta.21 → 0.11.0-beta.22

package/README.md

@@ -1,4 +1,4 @@
-# Proton UI
+# ProtonUI
 
 ![](./.readme.gif)
 
@@ -6,68 +6,148 @@
 npm run storybook
 ```
 
-### Publishing Updates to NPM
+## Installation
 
-```
-npm run build
-npm version <new_version>  // increment version in package.json accordingly using semver
-npm publish
+### Prerequisites
+
+1. Ensure you have access to `@protonradio/proton-ui` [npm package](https://www.npmjs.com/package/@protonradio/proton-ui)
+2. Login using `npm login`
+
+### Install
+
+```bash
+npm install @protonradio/proton-ui --save
 ```
 
-### Themes
+### Import Styles
 
-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.
+Import the styles into your main CSS file:
 
-#### Adding a Theme
+```css
+@import "@protonradio/proton-ui/styles";
+```
 
-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]`.
+### Setup ThemeProvider
 
-#### Styling for a theme
+Wrap your application with the `ThemeProvider` to enable theming:
 
-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.
+```jsx
+import { ThemeProvider, THEMES } from "@protonradio/proton-ui";
 
-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;
+function MyApp({ Component, pageProps }) {
+  return (
+    <ThemeProvider theme={THEMES.DARK}>
+      <Component {...pageProps} />
+    </ThemeProvider>
+  );
 }
 ```
 
-### Implementing in your application
+### Custom Color Palettes
+
+Each theme has a `ProtonPalette` with colors tailored for UI design. Palettes are made up of `ProtonColorScale`s that have shades from super_light to super_dark:
 
-#### Prerequisites
+- **Primary Scale**
+- **Secondary Scale**
+- **Brand Colors** [Partial ProtonColorScale]
+- **Gray Scale**
+- **Semantic Colors**
+  - Success
+  - Warning
+  - Error
 
-1. Ensure you have access to Proton's `proton-ui` npm package
-2. Login to npm using `npm login`
+When you pass a custom palette to the ThemeProvider, these five scales are updated with colors based on the background image you gave it. This is useful for designing UIs around individual releases, labels and artists. All generated scales are designed with accessibility in mind, ensuring proper contrast ratios and visual hierarchy.
 
-#### Install
+To generate a new palette, use the `usePalette` hook:
+
+```jsx
+import { ThemeProvider, usePalette, THEMES } from "@protonradio/proton-ui";
+
+function AppWithCustomPalette(props) {
+  const customPalette = usePalette(
+    `https://example.com/${props.imgUrl}.jpg`,
+    THEMES.DARK
+  );
 
+  return (
+    <ThemeProvider theme={THEMES.DARK} palette={customPalette}>
+      <YourApp />
+    </ThemeProvider>
+  );
+}
 ```
-npm install @protonradio/proton-ui --save
+
+## Best Styling Practices
+
+Components use standardized _control_ variables defined in the theme config stylesheets for consistent styling across the design system:
+
+```typescript
+export interface ProtonStyleSheet {
+  "--proton-control__background-color": string;
+  "--proton-control__background-color-light": string;
+  "--proton-control__text-color": string;
+  "--proton-control__title-color": string;
+  "--proton-control__border-color": string;
+  "--proton-control__shadow-color": string;
+  // ... etc
 ```
 
-#### Import the styles
-Then import the styles into your main.css file.
+These control variables unify the styling system while powering theme-specific CSS customization, and follow the pattern `--proton-control__{style}-{property}`:
 
 ```css
-@import "@protonradio/proton-ui/styles";
+.myComponent {
+  background-color: var(--proton-control__background-color);
+}
+```
+
+For more advanced theme overrides we utilize the theme class names. The `ThemeProvider` applies the appropriate theme class to its container, making it available to all child components. Theme class names follow the pattern `proton-ui__theme--{themeName}`:
+
+```css
+.proton-ui__theme--dark .myComponent[active] {
+  background-color: var(--proton-control__interactive-color);
+}
 ```
 
-#### Setup the theme provider
-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.
+Palettes can also be accessed in JSX via the `useTheme` hook for more advanced use cases:
+
 
 ```jsx
-import { ThemeProvider, THEMES } from "@protonradio/proton-ui";
+import { useTheme } from "@protonradio/proton-ui";
 
-function MyApp({ Component, pageProps }) {
-  return (
-    <ThemeProvider theme={THEMES.DARK}>
-      <Component {...pageProps} />
-    </ThemeProvider>
-  );
+function MyComponent() {
+  const { palette } = useTheme();
+
+  // Prefer CSS selectors over programmatic styling
+  return <Icon color={palette.BRAND.PRIMARY} />;
 }
 ```
 
-### Recommended Reading
+## Publishing Updates to NPM
+
+We follow semantic versioning and use automated CI/CD for releases:
+
+**For Beta Releases (Testing):**
+
+```bash
+npm run build
+npm run publish-beta  # Automated versioning with beta tag
+```
+
+**For Production Releases:**
+
+```bash
+npm run build
+npm version <patch|minor|major>  # Semantic versioning
+npm publish
+```
+
+**Best Practices:**
+
+- Always publish beta releases first for testing across platforms
+- Test on all supported environments before production release
+- Use semantic versioning (patch for bug fixes, minor for features, major for breaking changes)
+- Our GitHub Actions [NPM Version](https://github.com/protonradio/proton-ui/actions/workflows/npm_release.yml) tool automatically handles versioning and deployment workflows
+
+## Recommended Reading
 
 - https://www.gabe.pizza/notes-on-component-libraries/

package/dist/breakpoint-9y1_8U_b.mjs

@@ -0,0 +1,10 @@
+const A = {
+  SMALL: 576,
+  MEDIUM: 768,
+  LARGE: 992,
+  X_LARGE: 1200
+};
+export {
+  A as B
+};
+//# sourceMappingURL=breakpoint-9y1_8U_b.mjs.map

package/dist/breakpoint-9y1_8U_b.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakpoint-9y1_8U_b.mjs","sources":["../src/constants/breakpoint.ts"],"sourcesContent":["export const BREAKPOINTS = {\r\n  SMALL: 576,\r\n  MEDIUM: 768,\r\n  LARGE: 992,\r\n  X_LARGE: 1200,\r\n};\r\n\r\nexport type Breakpoint = (typeof BREAKPOINTS)[keyof typeof BREAKPOINTS];\r\n"],"names":["BREAKPOINTS"],"mappings":"AAAO,MAAMA,IAAc;AAAA,EACzB,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,SAAS;AACX;"}

package/dist/breakpoint-DtqbboOa.js

@@ -0,0 +1,2 @@
+"use strict";const A={SMALL:576,MEDIUM:768,LARGE:992,X_LARGE:1200};exports.BREAKPOINTS=A;
+//# sourceMappingURL=breakpoint-DtqbboOa.js.map

package/dist/breakpoint-DtqbboOa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"breakpoint-DtqbboOa.js","sources":["../src/constants/breakpoint.ts"],"sourcesContent":["export const BREAKPOINTS = {\r\n  SMALL: 576,\r\n  MEDIUM: 768,\r\n  LARGE: 992,\r\n  X_LARGE: 1200,\r\n};\r\n\r\nexport type Breakpoint = (typeof BREAKPOINTS)[keyof typeof BREAKPOINTS];\r\n"],"names":["BREAKPOINTS"],"mappings":"aAAO,MAAMA,EAAc,CACzB,MAAO,IACP,OAAQ,IACR,MAAO,IACP,QAAS,IACX"}

package/dist/constants.cjs.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("./palettes-DfloGKJz.js"),o={DARK:"dark",CUSTOM_DARK:"custom-dark",LIGHT:"light"},e=["bottom","bottom left","bottom right","bottom start","bottom end","top","top left","top right","top start","top end","left","left top","left bottom","start","start top","start bottom","right","right top","right bottom","end","end top","end bottom"],r={SMALL:576,MEDIUM:768,LARGE:992,X_LARGE:1200};exports.COLORS=t.colors;exports.DARK_MODE=t.DARK_MODE;exports.DEFAULT_BLACK_BACKGROUND=t.DEFAULT_BLACK_BACKGROUND;exports.DEFAULT_WHITE_BACKGROUND=t.DEFAULT_WHITE_BACKGROUND;exports.LIGHT_MODE=t.LIGHT_MODE;exports.BREAKPOINTS=r;exports.THEMES=o;exports.placements=e;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("./breakpoint-DtqbboOa.js"),t=require("./theme-Dc0Ahjq9.js"),e=["bottom","bottom left","bottom right","bottom start","bottom end","top","top left","top right","top start","top end","left","left top","left bottom","start","start top","start bottom","right","right top","right bottom","end","end top","end bottom"];exports.BREAKPOINTS=o.BREAKPOINTS;exports.THEMES=t.THEMES;exports.THEME_CLASSES=t.THEME_CLASSES;exports.placements=e;
 //# sourceMappingURL=constants.cjs.js.map

package/dist/constants.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.cjs.js","sources":["../src/constants/index.ts"],"sourcesContent":["import { Placement } from \"react-aria\";\r\n\r\nexport * as COLORS from \"./colors\";\r\n\r\nexport * from \"./palettes\";\r\n\r\nexport const THEMES = {\r\n  DARK: \"dark\",\r\n  CUSTOM_DARK: \"custom-dark\",\r\n  LIGHT: \"light\",\r\n} as const;\r\n\r\nexport type Theme = (typeof THEMES)[keyof typeof THEMES];\r\n\r\nexport const placements: Placement[] = [\r\n  \"bottom\",\r\n  \"bottom left\",\r\n  \"bottom right\",\r\n  \"bottom start\",\r\n  \"bottom end\",\r\n  \"top\",\r\n  \"top left\",\r\n  \"top right\",\r\n  \"top start\",\r\n  \"top end\",\r\n  \"left\",\r\n  \"left top\",\r\n  \"left bottom\",\r\n  \"start\",\r\n  \"start top\",\r\n  \"start bottom\",\r\n  \"right\",\r\n  \"right top\",\r\n  \"right bottom\",\r\n  \"end\",\r\n  \"end top\",\r\n  \"end bottom\",\r\n];\r\n\r\nexport const BREAKPOINTS = {\r\n  SMALL: 576,\r\n  MEDIUM: 768,\r\n  LARGE: 992,\r\n  X_LARGE: 1200,\r\n};\r\n\r\nexport type Breakpoint = (typeof BREAKPOINTS)[keyof typeof BREAKPOINTS];\r\n"],"names":["THEMES","placements","BREAKPOINTS"],"mappings":"0HAMaA,EAAS,CACpB,KAAM,OACN,YAAa,cACb,MAAO,OACT,EAIaC,EAA0B,CACrC,SACA,cACA,eACA,eACA,aACA,MACA,WACA,YACA,YACA,UACA,OACA,WACA,cACA,QACA,YACA,eACA,QACA,YACA,eACA,MACA,UACA,YACF,EAEaC,EAAc,CACzB,MAAO,IACP,OAAQ,IACR,MAAO,IACP,QAAS,IACX"}
+{"version":3,"file":"constants.cjs.js","sources":["../src/constants/placement.ts"],"sourcesContent":["import { Placement } from \"react-aria\";\r\n\r\nexport const placements: Placement[] = [\r\n  \"bottom\",\r\n  \"bottom left\",\r\n  \"bottom right\",\r\n  \"bottom start\",\r\n  \"bottom end\",\r\n  \"top\",\r\n  \"top left\",\r\n  \"top right\",\r\n  \"top start\",\r\n  \"top end\",\r\n  \"left\",\r\n  \"left top\",\r\n  \"left bottom\",\r\n  \"start\",\r\n  \"start top\",\r\n  \"start bottom\",\r\n  \"right\",\r\n  \"right top\",\r\n  \"right bottom\",\r\n  \"end\",\r\n  \"end top\",\r\n  \"end bottom\",\r\n];\r\n"],"names":["placements"],"mappings":"6JAEaA,EAA0B,CACrC,SACA,cACA,eACA,eACA,aACA,MACA,WACA,YACA,YACA,UACA,OACA,WACA,cACA,QACA,YACA,eACA,QACA,YACA,eACA,MACA,UACA,YACF"}

package/dist/constants.d.ts

@@ -1,12 +1,5 @@
 import { Placement } from 'react-aria';
 
-declare const BRAND: {
-    PRIMARY: string;
-    PRIMARY_LIGHT: string;
-    PRIMARY_SUPER_LIGHT: string;
-    SECONDARY: string;
-};
-
 export declare type Breakpoint = (typeof BREAKPOINTS)[keyof typeof BREAKPOINTS];
 
 export declare const BREAKPOINTS: {
@@ -16,156 +9,18 @@ export declare const BREAKPOINTS: {
     X_LARGE: number;
 };
 
-export declare namespace COLORS {
-    export {
-        BRAND,
-        DANGER,
-        WARNING,
-        SUCCESS,
-        GRAYSCALE,
-        SECONDARY,
-        DARK_GRAYSCALE,
-        DARK_SECONDARY
-    }
-}
-
-declare const DANGER: {
-    SUPER_DARK: string;
-    DARK: string;
-    MEDIUM: string;
-    LIGHT: string;
-    SUPER_LIGHT: string;
-};
-
-declare const DARK_GRAYSCALE: {
-    GRAY_SUPER_DARK: string;
-    GRAY_DARK: string;
-    GRAY_MEDIUM: string;
-    GRAY_MEDIUM_LIGHT: string;
-    GRAY_LIGHT: string;
-    GRAY_LIGHTEST: string;
-    GRAY_SUPER_LIGHT: string;
-    WHITE: string;
-    BORDER: string;
-    ELEVATION: string;
-};
-
-export declare const DARK_MODE: Palette;
-
-declare const DARK_SECONDARY: {
-    SECONDARY_SUPER_DARK: string;
-    SECONDARY_DARK: string;
-    SECONDARY_MEDIUM: string;
-    SECONDARY_MEDIUM_LIGHT: string;
-    SECONDARY_LIGHT: string;
-    SECONDARY_LIGHTEST: string;
-    SECONDARY_SUPER_LIGHT: string;
-};
-
-export declare const DEFAULT_BLACK_BACKGROUND = "#121212";
-
-export declare const DEFAULT_WHITE_BACKGROUND = "#ffffff";
-
-declare const GRAYSCALE: {
-    GRAY_SUPER_DARK: string;
-    GRAY_DARK: string;
-    GRAY_MEDIUM: string;
-    GRAY_MEDIUM_LIGHT: string;
-    GRAY_LIGHT: string;
-    GRAY_LIGHTEST: string;
-    GRAY_SUPER_LIGHT: string;
-    WHITE: string;
-    BORDER: string;
-    ELEVATION: string;
-};
-
-export declare const LIGHT_MODE: Palette;
-
-export declare type Palette = {
-    BASE_COLOR: string;
-    BRAND: {
-        PRIMARY: string;
-        PRIMARY_LIGHT: string;
-        PRIMARY_SUPER_LIGHT: string;
-        SECONDARY: string;
-    };
-    PRIMARY: {
-        PRIMARY_SUPER_DARK: string;
-        PRIMARY_DARK: string;
-        PRIMARY_MEDIUM: string;
-        PRIMARY_MEDIUM_LIGHT: string;
-        PRIMARY_LIGHT: string;
-        PRIMARY_LIGHTEST: string;
-        PRIMARY_SUPER_LIGHT: string;
-    };
-    SECONDARY: {
-        SECONDARY_SUPER_DARK: string;
-        SECONDARY_DARK: string;
-        SECONDARY_MEDIUM: string;
-        SECONDARY_MEDIUM_LIGHT: string;
-        SECONDARY_LIGHT: string;
-        SECONDARY_LIGHTEST: string;
-        SECONDARY_SUPER_LIGHT: string;
-    };
-    SUCCESS: {
-        SUCCESS_DARK: string;
-        SUCCESS_MEDIUM: string;
-        SUCCESS_LIGHT: string;
-        SUCCESS_SUPER_LIGHT: string;
-    };
-    WARNING: {
-        WARNING_DARK: string;
-        WARNING_MEDIUM: string;
-        WARNING_LIGHT: string;
-        WARNING_SUPER_LIGHT: string;
-    };
-    DANGER: {
-        DANGER_SUPER_DARK: string;
-        DANGER_DARK: string;
-        DANGER_MEDIUM: string;
-        DANGER_LIGHT: string;
-        DANGER_SUPER_LIGHT: string;
-    };
-};
-
 export declare const placements: Placement[];
 
-declare const SECONDARY: {
-    SUPER_DARK: string;
-    DARK: string;
-    MEDIUM: string;
-    MEDIUM_LIGHT: string;
-    LIGHT: string;
-    LIGHTEST: string;
-    SUPER_LIGHT: string;
-    WHITE: string;
-};
+export declare type Theme = (typeof THEMES)[keyof typeof THEMES];
 
-declare const SUCCESS: {
-    DARK: string;
-    MEDIUM: string;
-    LIGHT: string;
-    SUPER_LIGHT: string;
+export declare const THEME_CLASSES: {
+    dark: string;
+    light: string;
 };
 
-export declare type Theme = (typeof THEMES)[keyof typeof THEMES];
-
 export declare const THEMES: {
     readonly DARK: "dark";
-    readonly CUSTOM_DARK: "custom-dark";
     readonly LIGHT: "light";
 };
 
-declare const WARNING: {
-    DARK: string;
-    MEDIUM: string;
-    LIGHT: string;
-    SUPER_LIGHT: string;
-};
-
 export { }
-
-
-declare namespace ButtonGroup {
-    var Option: (props: ButtonGroupOptionProps) => import("react/jsx-runtime").JSX.Element;
-}

package/dist/constants.es.js

@@ -1,9 +1,6 @@
-import { c as e, b as m, a as p, D as A, L as D } from "./palettes-D006-kxf.mjs";
-const t = {
-  DARK: "dark",
-  CUSTOM_DARK: "custom-dark",
-  LIGHT: "light"
-}, o = [
+import { B as r } from "./breakpoint-9y1_8U_b.mjs";
+import { T as m, a } from "./theme-DQsfWeLo.mjs";
+const t = [
   "bottom",
   "bottom left",
   "bottom right",
@@ -26,20 +23,11 @@ const t = {
   "end",
   "end top",
   "end bottom"
-], r = {
-  SMALL: 576,
-  MEDIUM: 768,
-  LARGE: 992,
-  X_LARGE: 1200
-};
+];
 export {
   r as BREAKPOINTS,
-  e as COLORS,
-  m as DARK_MODE,
-  p as DEFAULT_BLACK_BACKGROUND,
-  A as DEFAULT_WHITE_BACKGROUND,
-  D as LIGHT_MODE,
-  t as THEMES,
-  o as placements
+  m as THEMES,
+  a as THEME_CLASSES,
+  t as placements
 };
 //# sourceMappingURL=constants.es.js.map

package/dist/constants.es.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.es.js","sources":["../src/constants/index.ts"],"sourcesContent":["import { Placement } from \"react-aria\";\r\n\r\nexport * as COLORS from \"./colors\";\r\n\r\nexport * from \"./palettes\";\r\n\r\nexport const THEMES = {\r\n  DARK: \"dark\",\r\n  CUSTOM_DARK: \"custom-dark\",\r\n  LIGHT: \"light\",\r\n} as const;\r\n\r\nexport type Theme = (typeof THEMES)[keyof typeof THEMES];\r\n\r\nexport const placements: Placement[] = [\r\n  \"bottom\",\r\n  \"bottom left\",\r\n  \"bottom right\",\r\n  \"bottom start\",\r\n  \"bottom end\",\r\n  \"top\",\r\n  \"top left\",\r\n  \"top right\",\r\n  \"top start\",\r\n  \"top end\",\r\n  \"left\",\r\n  \"left top\",\r\n  \"left bottom\",\r\n  \"start\",\r\n  \"start top\",\r\n  \"start bottom\",\r\n  \"right\",\r\n  \"right top\",\r\n  \"right bottom\",\r\n  \"end\",\r\n  \"end top\",\r\n  \"end bottom\",\r\n];\r\n\r\nexport const BREAKPOINTS = {\r\n  SMALL: 576,\r\n  MEDIUM: 768,\r\n  LARGE: 992,\r\n  X_LARGE: 1200,\r\n};\r\n\r\nexport type Breakpoint = (typeof BREAKPOINTS)[keyof typeof BREAKPOINTS];\r\n"],"names":["THEMES","placements","BREAKPOINTS"],"mappings":";AAMO,MAAMA,IAAS;AAAA,EACpB,MAAM;AAAA,EACN,aAAa;AAAA,EACb,OAAO;AACT,GAIaC,IAA0B;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAEaC,IAAc;AAAA,EACzB,OAAO;AAAA,EACP,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,SAAS;AACX;"}
+{"version":3,"file":"constants.es.js","sources":["../src/constants/placement.ts"],"sourcesContent":["import { Placement } from \"react-aria\";\r\n\r\nexport const placements: Placement[] = [\r\n  \"bottom\",\r\n  \"bottom left\",\r\n  \"bottom right\",\r\n  \"bottom start\",\r\n  \"bottom end\",\r\n  \"top\",\r\n  \"top left\",\r\n  \"top right\",\r\n  \"top start\",\r\n  \"top end\",\r\n  \"left\",\r\n  \"left top\",\r\n  \"left bottom\",\r\n  \"start\",\r\n  \"start top\",\r\n  \"start bottom\",\r\n  \"right\",\r\n  \"right top\",\r\n  \"right bottom\",\r\n  \"end\",\r\n  \"end top\",\r\n  \"end bottom\",\r\n];\r\n"],"names":["placements"],"mappings":";;AAEO,MAAMA,IAA0B;AAAA,EACrC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;"}