@propelinc/citrus-ui 0.5.1 → 1.0.0

package/README.md

@@ -4,93 +4,63 @@ Propel's UI component library.
 
 See what components are currently available in [Storybook](https://storybook.providersapp.com/).
 
-Also, see the Citrus UI slack channel #proj-citrus-design-system.
-
-## Setup
-
-```bash
-nvm use # Switches to the correct version of node
-npm install # Install dependencies
-```
-
-### VSCode Setup
-
-First, install:
-
-- [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) - highlights ESLint errors in your editor
-- [Stylelint](https://marketplace.visualstudio.com/items?itemName=stylelint.vscode-stylelint) - highligths Stylelint errors in your editor
-
-Once you install the ESLint and Stylelint extensions, VSCode can fix lint errors when you save a file.
-
-To set this up:
-
-1. Head over to your VSCode settings
-2. Search for `editor.codeActionsOnSave` and click "Edit in settings.json"
-3. Add this configuration:
-
-```json
-"editor.codeActionsOnSave": {
-  "source.fixAll.eslint": true,
-  "source.fixAll.stylelint": true,
-},
-```
-
-## Development
-
-### Storybook
-
-Unlike a normal Vue project, we don't use a dev server to compile an app. Instead, we rely on [Storybook](https://storybook.js.org/) to render and manually test our components.
-
-
-```bash
-npm run serve:storybook
-```
-
-### Testing
-
-Since there is no app to test, there are no e2e tests. Instead, all tests are written in jest. You can make sure you components render correctly using Storybook.
-
-```bash
-npm run test:unit
-```
-
-### Linting
-
-```bash
-npm run lint:js # Runs ESLint + Prettier
-npm run lint:css # Runs Stylelint
-```
-
-### Adding a component
-
-To add a new component, first generate the component with plop.
-
-```bash
-npm run generate:component # Interactive CLI
-npm run generate:component -- [name] [directory] [document in storybook] # Shortcuts
+Questions? Ask for eng help in [#unit-eng-frontend-libraries](https://propel-team.slack.com/archives/C02F363U5RB). Get answers to design or cross-functional questions in [#wg-citrus-design-system](https://propel-team.slack.com/archives/C02004PUH5M).
+
+## Docs
+
+| Page                                               | Description                             |
+| -------------------------------------------------- | --------------------------------------- |
+| [Development](/libs/citrus-ui/docs/DEVELOPMENT.md) | Linting, testing, and adding components |
+| [Style Guide](/libs/citrus-ui/docs/STYLE_GUIDE.md) | Guidelines for code styles              |
+
+---
+
+## CDN Usage
+
+citrus-ui is published to npm as `@propelinc/citrus-ui` and can be loaded via jsDelivr or unpkg. The following peer dependencies must be loaded separately.
+
+> **Note:** `@fortawesome/pro-*` packages require a paid FontAwesome Pro license and are not available on public CDNs. Components that use icons (`CButton`, `CLabel`, `CCheckbox`, `CTextField`, `CSelect`, and others) will not render icons without FontAwesome Pro. See [CDN challenges](#cdn-challenges) below.
+
+```html
+<!-- Shoelace styles + assets -->
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.15.0/cdn/themes/light.css"
+/>
+<script type="module">
+  import { setBasePath } from 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.15.0/cdn/shoelace-autoloader.js';
+  setBasePath('https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.15.0/cdn/');
+</script>
+
+<!-- FontAwesome Pro (self-hosted — not available on public CDNs) -->
+<script src="YOUR_SELF_HOSTED_FONTAWESOME_PRO_URL"></script>
+
+<!-- citrus-ui styles -->
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@propelinc/citrus-ui@1.0.0/dist/styles/main.css"
+/>
+
+<!-- citrus-ui + Vue -->
+<script type="module">
+  import { createApp } from 'https://cdn.jsdelivr.net/npm/vue@3/dist/vue.esm-browser.prod.js';
+  import CitrusUi from 'https://cdn.jsdelivr.net/npm/@propelinc/citrus-ui@1.0.0/dist/index.mjs';
+
+  const app = createApp({
+    /* ... */
+  });
+  app.use(CitrusUi);
+  app.mount('#app');
+</script>
 ```
 
-❗️ If you want the component to be available to your Vue app, you'll need to add the component to [index.ts](https://github.com/propelinc/citrus-ui/blob/main/src/index.ts) and define the type in [index.d.ts](https://github.com/propelinc/citrus-ui/blob/main/src/index.d.ts).
+### CDN Challenges
 
-## Publishing
-
-When publishing a new version, bump the version in the package.json according to [semantic versioning](https://semver.org/)
-. 
-
-Then, run:
-
-```bash
-npm run publish:dist
-```
-
-Finally, announce the new version in #proj-citrus-design-system.
-
-### NPM Access
-
-Because this package is published to our internal NPM repository, you'll need an [NPM account](https://www.npmjs.com/) and to be part of the [@propelinc organization](https://www.npmjs.com/org/propelinc) to publish. Once you have that set up, you'll have to login: 
-
-```bash
-npm login --scope=@propelinc
-```
+| Dependency                                  | CDN available? | Notes                                                 |
+| ------------------------------------------- | -------------- | ----------------------------------------------------- |
+| `vue`                                       | ✅             | jsDelivr / unpkg                                      |
+| `@shoelace-style/shoelace`                  | ✅             | Requires `setBasePath` to point at CDN assets         |
+| `dayjs`, `lodash`, `i18next`, `maska`, etc. | ✅             | All on public npm, available via CDN                  |
+| `@fortawesome/pro-*`                        | ❌             | Paid license, not on public npm — must be self-hosted |
 
-Or alternatively, just ask Mohan to publish for you.
+Because FontAwesome Pro cannot be served from a public CDN, components that render icons will require a self-hosted FontAwesome Pro bundle or an alternative delivery mechanism for those packages.

package/dist/colors/colors.d.ts

@@ -0,0 +1,31 @@
+export type HexColor = `#${string}`;
+export type RgbaColor = `rgba(${number}, ${number}, ${number}, ${number})`;
+/**
+ * CSS color value from the palette (hex or rgba). Use this type when a value
+ * may be either format, e.g. gray colors are rgba, others are hex.
+ */
+export type CssColor = HexColor | RgbaColor;
+/**
+ * Maps a color name to its corresponding CSS color (hex or rgba).
+ * Gray neutrals use rgba for transparency; other colors use hex.
+ *
+ * NOTE: Please write hex codes in lowercase letters
+ */
+declare const Colors: Record<string, CssColor>;
+export default Colors;
+/**
+ * This is a type predicate that will allow TypeScript to know that the string tested is a
+ * HexColor within the scope of the narrowing.
+ */
+export declare function isHexColor(color?: string): color is HexColor;
+export declare function isRgbaColor(color?: string): color is RgbaColor;
+export declare function isCssColor(color?: string): color is CssColor;
+/**
+ * This is a type predicate that will allow TypeScript to know that the string tested is a
+ * key of the Colors object.
+ */
+export declare function isColorKey(color?: string): color is keyof typeof Colors;
+/**
+ * Validates a string as either a hex color or a color key.
+ */
+export declare function isValidColor(value: string): boolean;

package/dist/colors/theme.d.ts

@@ -1,12 +1,3 @@
-declare const _default: {
-    [x: string]: import("vuetify/types/services/theme").VuetifyThemeItem;
-    primary?: import("vuetify/types/services/theme").VuetifyThemeItem;
-    secondary?: import("vuetify/types/services/theme").VuetifyThemeItem;
-    accent?: import("vuetify/types/services/theme").VuetifyThemeItem;
-    info?: import("vuetify/types/services/theme").VuetifyThemeItem;
-    warning?: import("vuetify/types/services/theme").VuetifyThemeItem;
-    error?: import("vuetify/types/services/theme").VuetifyThemeItem;
-    success?: import("vuetify/types/services/theme").VuetifyThemeItem;
-    anchor?: string | number | undefined;
-};
+type Theme = Record<string, string>;
+declare const _default: Theme;
 export default _default;

package/dist/colors/util-classes.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Generates utility classes for each Citrus color.
+ *
+ * For example, for blue-500 it creates:
+ * - `.blue-500` - sets background and border
+ * - `.blue-500--text` - sets text color
+ *
+ * This matches the syntax of Vuetify's utils:
+ * https://vuetifyjs.com/en/styles/colors/#classes
+ */
+export declare function addColorUtils(): void;

package/dist/components/CAccordion.vue.d.ts

@@ -0,0 +1,21 @@
+import { DefineComponent, ExtractPropTypes, Ref, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+declare const _default: DefineComponent<ExtractPropTypes<{
+    /** Removes horizontal padding for all items inside */
+    fluid: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>, {
+    accordion: Ref<HTMLDivElement | null, HTMLDivElement | null>;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, "change"[], "change", PublicProps, Readonly< ExtractPropTypes<{
+    /** Removes horizontal padding for all items inside */
+    fluid: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+}>> & Readonly<{
+    onChange?: ((...args: any[]) => any) | undefined;
+}>, {
+    fluid: boolean;
+}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/components/CAccordionItem.vue.d.ts

@@ -0,0 +1,41 @@
+import { default as SlDetails } from '@shoelace-style/shoelace/dist/components/details/details';
+import { PropType, DefineComponent, ExtractPropTypes, Ref, ComputedRef, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+import { IconDefinition } from '@fortawesome/pro-regular-svg-icons';
+import { FontAwesomeIconProps } from '@fortawesome/vue-fontawesome';
+declare const _default: DefineComponent<ExtractPropTypes<{
+    /** Controls whether the item is open */
+    value: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Removes horizontal padding from the content */
+    fluid: {
+        type: PropType<boolean | null>;
+        default: null;
+    };
+}>, {
+    internalValue: Ref<boolean, boolean>;
+    faChevronDown: IconDefinition;
+    details: Ref<SlDetails | null, SlDetails | null>;
+    injectedOrPropFluid: ComputedRef<boolean>;
+    onChange: (value: boolean) => void;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, "input"[], "input", PublicProps, Readonly< ExtractPropTypes<{
+    /** Controls whether the item is open */
+    value: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Removes horizontal padding from the content */
+    fluid: {
+        type: PropType<boolean | null>;
+        default: null;
+    };
+}>> & Readonly<{
+    onInput?: ((...args: any[]) => any) | undefined;
+}>, {
+    fluid: boolean | null;
+    value: boolean;
+}, {}, {
+    FontAwesomeIcon: DefineComponent<FontAwesomeIconProps>;
+}, {}, string, ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/components/CAppBar.vue.d.ts

@@ -0,0 +1,156 @@
+import { PropType, DefineComponent, ExtractPropTypes, Ref, ComputedRef, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+import { HexColor, default as Colors, isValidColor, CssColor } from '../colors/colors';
+declare const _default: DefineComponent<ExtractPropTypes<{
+    /**
+     * Used to set the background color of the app bar. Needs to accept either a hex code or a
+     * a valid color key from the Colors object.
+     */
+    backgroundColor: {
+        type: PropType<HexColor | keyof typeof Colors>;
+        default: string;
+        validator: typeof isValidColor;
+    };
+    color: {
+        type: PropType<HexColor | keyof typeof Colors>;
+        default: undefined;
+        validator: typeof isValidColor;
+    };
+    /** If true, the app bar will be fixed to the top of the viewport. */
+    fixed: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** If true, the app bar will have a bottom border. */
+    border: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Shows text in the center of the component. Typically used for page names. Overrides the title slot. */
+    title: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** Shows a loading spinner. Overrides the title slot.  */
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Adds screen reader only text alternative to loading icon, text should be translated */
+    loaderAccessibleText: {
+        type: StringConstructor;
+        default: string;
+    };
+}>, {
+    bgCssColor: Ref< CssColor | undefined, CssColor | undefined>;
+    textCssColor: ComputedRef<CssColor>;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly< ExtractPropTypes<{
+    /**
+     * Used to set the background color of the app bar. Needs to accept either a hex code or a
+     * a valid color key from the Colors object.
+     */
+    backgroundColor: {
+        type: PropType<HexColor | keyof typeof Colors>;
+        default: string;
+        validator: typeof isValidColor;
+    };
+    color: {
+        type: PropType<HexColor | keyof typeof Colors>;
+        default: undefined;
+        validator: typeof isValidColor;
+    };
+    /** If true, the app bar will be fixed to the top of the viewport. */
+    fixed: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** If true, the app bar will have a bottom border. */
+    border: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Shows text in the center of the component. Typically used for page names. Overrides the title slot. */
+    title: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** Shows a loading spinner. Overrides the title slot.  */
+    loading: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Adds screen reader only text alternative to loading icon, text should be translated */
+    loaderAccessibleText: {
+        type: StringConstructor;
+        default: string;
+    };
+}>> & Readonly<{}>, {
+    title: string;
+    border: boolean;
+    fixed: boolean;
+    color: string;
+    backgroundColor: string;
+    loading: boolean;
+    loaderAccessibleText: string;
+}, {}, {
+    CLoader: DefineComponent<ExtractPropTypes<{
+        accessibleText: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        color: {
+            type: PropType<HexColor | keyof typeof Colors>;
+            default: string;
+            validator: typeof isValidColor;
+        };
+        small: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        size: {
+            type: PropType<"sm" | "lg" | "md">;
+            default: string;
+        };
+        trackColor: {
+            type: PropType<HexColor | keyof typeof Colors>;
+            default: string;
+            validator: typeof isValidColor;
+        };
+    }>, {
+        computedSize: ComputedRef<"sm" | "lg" | "md">;
+        indicatorColorCode: Ref< CssColor | undefined, CssColor | undefined>;
+        SIZE_TO_FONT_SIZE: Record<"sm" | "lg" | "md", `${number}px`>;
+        SIZE_TO_TRACK_WIDTH: Record<"sm" | "lg" | "md", `${number}px`>;
+        trackColorCode: Ref< CssColor | undefined, CssColor | undefined>;
+    }, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly< ExtractPropTypes<{
+        accessibleText: {
+            type: StringConstructor;
+            default: undefined;
+        };
+        color: {
+            type: PropType<HexColor | keyof typeof Colors>;
+            default: string;
+            validator: typeof isValidColor;
+        };
+        small: {
+            type: BooleanConstructor;
+            default: boolean;
+        };
+        size: {
+            type: PropType<"sm" | "lg" | "md">;
+            default: string;
+        };
+        trackColor: {
+            type: PropType<HexColor | keyof typeof Colors>;
+            default: string;
+            validator: typeof isValidColor;
+        };
+    }>> & Readonly<{}>, {
+        small: boolean;
+        size: "sm" | "lg" | "md";
+        accessibleText: string;
+        color: string;
+        trackColor: string;
+    }, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+    CFadeTransition: DefineComponent<{}, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+}, {}, string, ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/components/CBadge.vue.d.ts

@@ -0,0 +1,52 @@
+import { DefineComponent, ExtractPropTypes, ComputedRef, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+declare const _default: DefineComponent<ExtractPropTypes<{
+    /** Sets the text of the badge, can also use default slot */
+    text: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    /** Adds a unique data-test attribute for testing to the container */
+    dataTest: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** Sets the background color */
+    color: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** Sets the text color */
+    textColor: {
+        type: StringConstructor;
+        default: string;
+    };
+}>, {
+    computedStyle: ComputedRef<Record<string, string>>;
+}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly< ExtractPropTypes<{
+    /** Sets the text of the badge, can also use default slot */
+    text: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    /** Adds a unique data-test attribute for testing to the container */
+    dataTest: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** Sets the background color */
+    color: {
+        type: StringConstructor;
+        default: string;
+    };
+    /** Sets the text color */
+    textColor: {
+        type: StringConstructor;
+        default: string;
+    };
+}>> & Readonly<{}>, {
+    text: string;
+    dataTest: string;
+    color: string;
+    textColor: string;
+}, {}, {}, {}, string, ComponentProvideOptions, true, {}, any>;
+export default _default;