mcr-design-systems 1.0.0 → 1.0.2

package/README.md

@@ -93,6 +93,189 @@ To check for code quality issues:
 yarn lint
 ```
 
+## Library Usage
+
+### Installation
+
+Install the library in your project:
+
+```bash
+npm install mcr-design-system
+# or
+yarn add mcr-design-system
+```
+
+### Setup with Tailwind CSS v4
+
+For projects using **Tailwind CSS v4** (recommended):
+
+1. Install Tailwind CSS v4:
+
+```bash
+npm install tailwindcss@next @tailwindcss/vite
+# or
+yarn add tailwindcss@next @tailwindcss/vite
+```
+
+2. Configure Vite to use the Tailwind plugin (`vite.config.ts`):
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: {
+      '@': resolve(__dirname, './src'),
+    },
+  },
+});
+```
+
+3. Create your `tailwind.config.js` using the design system generator:
+
+```javascript
+import { generateTailwindConfig } from 'mcr-design-system';
+
+/** @type {import('tailwindcss').Config} */
+export default generateTailwindConfig();
+```
+
+4. Import Tailwind and configure in your main CSS file:
+
+```css
+@import 'tailwindcss';
+@config '../tailwind.config.js';
+
+/* Optional: Add any custom styles */
+```
+
+5. Wrap your app with the ThemeProvider:
+
+```tsx
+import { ThemeProvider } from 'mcr-design-system';
+
+function App() {
+  return <ThemeProvider>{/* Your app content */}</ThemeProvider>;
+}
+```
+
+### Setup with Tailwind CSS v3
+
+For projects using **Tailwind CSS v3**:
+
+1. Install Tailwind CSS v3:
+
+```bash
+npm install -D tailwindcss postcss autoprefixer
+# or
+yarn add -D tailwindcss postcss autoprefixer
+```
+
+2. Create/update your `tailwind.config.js`:
+
+```javascript
+import { generateTailwindConfig } from 'mcr-design-system';
+
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    './index.html',
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/mcr-design-system/dist/**/*.{js,ts,jsx,tsx}',
+  ],
+  ...generateTailwindConfig(), // Spreads design system tokens and configuration
+};
+```
+
+3. Configure PostCSS (`postcss.config.js`):
+
+```javascript
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+```
+
+4. Import Tailwind in your main CSS file:
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+5. Wrap your app with the ThemeProvider:
+
+```tsx
+import { ThemeProvider } from 'mcr-design-system';
+
+function App() {
+  return <ThemeProvider>{/* Your app content */}</ThemeProvider>;
+}
+```
+
+### Using Components
+
+Import and use components in your React application:
+
+```tsx
+import { Button, Alert, Typography, Badge } from 'mcr-design-system';
+
+function MyComponent() {
+  return (
+    <div>
+      <Typography variant="h1">Welcome</Typography>
+      <Button variant="primary" size="lg">
+        Click me
+      </Button>
+      <Alert variant="success">Operation completed successfully!</Alert>
+      <Badge variant="info">New</Badge>
+    </div>
+  );
+}
+```
+
+### TypeScript Support
+
+The library includes full TypeScript support. Import types as needed:
+
+```tsx
+import type { ButtonProps, AlertVariant } from 'mcr-design-system';
+
+interface MyComponentProps {
+  buttonProps: ButtonProps;
+  alertType: AlertVariant;
+}
+```
+
+### Design Token Access
+
+Access design tokens programmatically:
+
+```tsx
+import { useTheme } from 'mcr-design-system';
+
+function MyComponent() {
+  const theme = useTheme();
+
+  return (
+    <div
+      style={{
+        backgroundColor: theme.colors.bg.surface.level1,
+        color: theme.colors.fg.neutral.main,
+      }}
+    >
+      Custom styled content
+    </div>
+  );
+}
+```
+
 ## Project Structure
 
 ```
@@ -170,15 +353,31 @@ Note: This will automatically run the build process before publishing.
 
 - React 19.x
 - React DOM 19.x
-- Tailwind CSS 4.x
+- Tailwind CSS 4.x (for development)
 - TypeScript 5.x
 - Vite 7.x
 
+### Peer Dependencies (Required in consuming projects)
+
+- **React**: ^18.0.0 || ^19.0.0
+- **React DOM**: ^18.0.0 || ^19.0.0
+- **Tailwind CSS**: ^3.0.0 || ^4.0.0-next
+
 ### Development Tools
 
 - ESLint for code linting
 - Husky for git hooks
 - Vite Plugin DTS for TypeScript declarations
+- Tailwind Variants for component styling
+- Class Variance Authority for type-safe variants
+
+### Tailwind CSS Compatibility
+
+| Tailwind Version | Support Status   | Setup Method              |
+| ---------------- | ---------------- | ------------------------- |
+| v4.x (Next)      | ✅ Recommended   | Vite plugin + CSS imports |
+| v3.x             | ✅ Supported     | PostCSS + config merge    |
+| v2.x             | ❌ Not supported | -                         |
 
 ## Browser Support
 
@@ -200,6 +399,43 @@ This project supports modern browsers that are compatible with React 18+ and ES2
 2. **Node version**: Ensure you're using Node.js version 16 or higher
 3. **Dependencies**: Delete `node_modules` and `package-lock.json`, then run `yarn install` if you encounter dependency issues
 
+### Tailwind CSS Issues
+
+#### Styles not applying in consuming project
+
+**For Tailwind v4:**
+
+- Ensure your `tailwind.config.js` uses `generateTailwindConfig()` from the design system
+- Verify Vite configuration includes `@tailwindcss/vite` plugin
+- Check that your CSS imports `@import 'tailwindcss';` and `@config '../tailwind.config.js';`
+- Verify ThemeProvider wraps your app
+
+**For Tailwind v3:**
+
+- Verify `tailwind.config.js` includes the design system path in content array
+- Ensure `generateTailwindConfig()` is spread in your config: `...generateTailwindConfig()`
+- Check PostCSS configuration is correct
+- Verify standard Tailwind imports: `@tailwind base;`, `@tailwind components;`, `@tailwind utilities;`
+
+#### Design tokens not working
+
+1. Verify ThemeProvider is wrapping your application
+2. Check console for token loading errors
+3. Ensure proper CSS imports are in place
+
+#### Version conflicts
+
+If you encounter version conflicts between Tailwind v3 and v4:
+
+```bash
+# Clear node_modules and lock files
+rm -rf node_modules package-lock.json yarn.lock
+# Reinstall with specific Tailwind version
+npm install tailwindcss@^3.4.0  # for v3
+# or
+npm install tailwindcss@next    # for v4
+```
+
 ### Getting Help
 
 If you encounter issues:
@@ -208,3 +444,4 @@ If you encounter issues:
 2. Ensure all dependencies are properly installed
 3. Verify Node.js version compatibility
 4. Check the Vite documentation for additional configuration options
+5. Review Tailwind CSS documentation for version-specific setup

package/dist/components/Badge/index.d.ts

@@ -11,6 +11,7 @@ declare const badge: import('tailwind-variants').TVReturnType<{
         yellow: string;
         violet: string;
         outline: string;
+        boldest: string;
     };
     size: {
         sm: string;
@@ -42,6 +43,7 @@ declare const badge: import('tailwind-variants').TVReturnType<{
         yellow: string;
         violet: string;
         outline: string;
+        boldest: string;
     };
     size: {
         sm: string;
@@ -73,6 +75,7 @@ declare const badge: import('tailwind-variants').TVReturnType<{
         yellow: string;
         violet: string;
         outline: string;
+        boldest: string;
     };
     size: {
         sm: string;

package/dist/components/Badge/index.js

@@ -0,0 +1,186 @@
+import { jsx as r, jsxs as N } from "react/jsx-runtime";
+import l, { useMemo as f } from "react";
+import { tv as B } from "../../node_modules/tailwind-variants/dist/index.js";
+import { Typography as I } from "../Typography/index.js";
+import "clsx";
+import "tailwind-merge";
+import { dataTestId as _ } from "../../shared/utils/dataTestId.js";
+const j = {
+  info: "bg-fg-accent-info-strong",
+  success: "bg-fg-accent-success-strong",
+  warning: "bg-fg-accent-warning-strong",
+  error: "bg-fg-accent-error-strong",
+  yellow: "bg-fg-accent-yellow-strong",
+  violet: "bg-fg-accent-violet-strong",
+  neutral: "bg-fg-neutral-subtle",
+  outline: "bg-fg-neutral-subtle",
+  boldest: "bg-bg-selected-boldest-rest"
+}, D = B({
+  base: "font-medium inline-flex w-fit select-none items-center",
+  variants: {
+    variant: {
+      neutral: "border border-neutral-strong bg-bg-neutral-bold-rest",
+      info: "border border-info-light bg-bg-accent-info-subtle text-fg-accent-info-strong",
+      success: "border border-success-light bg-bg-accent-success-subtle text-fg-accent-success-strong",
+      warning: "border border-warning-light bg-bg-accent-warning-subtle text-fg-accent-warning-strong",
+      error: "border border-error-light bg-bg-accent-error-subtle text-fg-accent-error-strong",
+      yellow: "border border-yellow-light bg-bg-accent-yellow-subtle text-fg-accent-yellow-strong",
+      violet: "border border-violet-light bg-bg-accent-violet-subtle text-fg-accent-violet-strong",
+      outline: "bg-bg-surface-level-3 border border-neutral-strong text-fg-neutral-subtle",
+      boldest: "border border-warning-light bg-bg-selected-boldest-rest text-fg-selected-bold"
+    },
+    size: {
+      sm: "h-[16px] gap-xs-3 rounded-sm px-xs-3 py-none",
+      md: "h-[24px] gap-xs-4 rounded-md px-xs-2 py-xs-4"
+    },
+    pill: {
+      true: "rounded-full px-2",
+      false: ""
+    },
+    emphasize: {
+      true: "border-none text-fg-neutral-inverse-static",
+      false: ""
+    },
+    disabled: {
+      true: "pointer-events-none opacity-50",
+      false: ""
+    },
+    withIcon: {
+      true: "gap-1",
+      false: ""
+    }
+  },
+  defaultVariants: {
+    variant: "neutral",
+    size: "md",
+    pill: !1,
+    emphasize: !1,
+    disabled: !1,
+    withIcon: !1
+  },
+  compoundVariants: [
+    {
+      variant: "neutral",
+      emphasize: !1,
+      className: "text-fg-neutral-subtle"
+    },
+    {
+      variant: "neutral",
+      emphasize: !0,
+      className: " bg-bg-neutral-boldest-rest"
+      // className: 'border-none bg-red-500',
+    },
+    {
+      variant: "info",
+      emphasize: !0,
+      className: "bg-bg-accent-info-rest"
+    },
+    {
+      variant: "success",
+      emphasize: !0,
+      className: "bg-bg-accent-success-rest"
+    },
+    {
+      variant: "warning",
+      emphasize: !0,
+      className: "bg-bg-accent-warning-rest"
+    },
+    {
+      variant: "error",
+      emphasize: !0,
+      className: "bg-bg-accent-error-rest"
+    },
+    {
+      variant: "yellow",
+      emphasize: !0,
+      className: "bg-bg-accent-yellow-rest"
+    },
+    {
+      variant: "violet",
+      emphasize: !0,
+      className: "bg-bg-accent-violet-rest"
+    },
+    {
+      variant: "boldest",
+      emphasize: !0,
+      className: "bg-bg-selected-boldest-rest"
+    }
+  ]
+}), m = l.memo(({ icon: t, iconAriaLabel: e }) => /* @__PURE__ */ r(
+  "span",
+  {
+    "aria-label": e,
+    role: e ? "img" : void 0,
+    className: "flex items-center justify-center",
+    children: typeof t == "function" ? t({ size: 16, name: "user-03" }) : t
+  }
+));
+m.displayName = "BadgeIcon";
+const p = l.memo(({ variant: t, emphasize: e }) => /* @__PURE__ */ r(
+  "span",
+  {
+    className: `h-1.5 w-1.5 rounded-full ${e ? "bg-fg-neutral-inverse" : j[t]}`,
+    "aria-hidden": "true"
+  }
+));
+p.displayName = "BadgeDot";
+const O = l.forwardRef(
+  ({
+    children: t,
+    icon: e,
+    iconAriaLabel: h,
+    variant: a = "neutral",
+    size: n = "md",
+    pill: g = !1,
+    emphasize: v = !1,
+    disabled: s = !1,
+    className: c,
+    withIcon: i,
+    dataTestIdName: b = "Badge",
+    dot: u = !1,
+    ...x
+  }, w) => {
+    const o = a === "outline" ? !1 : v, { id: y } = f(() => _(b), [b]), d = !!e, z = f(
+      () => D({
+        variant: a,
+        size: n,
+        pill: g,
+        emphasize: o,
+        disabled: s,
+        withIcon: d || i,
+        className: c
+      }),
+      [
+        a,
+        n,
+        g,
+        o,
+        s,
+        d,
+        i,
+        c
+      ]
+    );
+    return !t && !e && !u ? null : /* @__PURE__ */ N(
+      "div",
+      {
+        ref: w,
+        className: z,
+        "aria-disabled": s || void 0,
+        role: "status",
+        tabIndex: s ? -1 : 0,
+        "data-testid": y,
+        ...x,
+        children: [
+          e && /* @__PURE__ */ r(m, { icon: e, iconAriaLabel: h }),
+          u && !e && /* @__PURE__ */ r(p, { variant: a, emphasize: o }),
+          t && /* @__PURE__ */ r(I, { variants: "action-emphasize", size: n, children: t })
+        ]
+      }
+    );
+  }
+);
+O.displayName = "Badge";
+export {
+  O as default
+};

package/dist/components/Breadcrumb/index.d.ts

@@ -0,0 +1,45 @@
+import { default as React } from 'react';
+export type BreadcrumbSeparator = 'slash' | 'dot' | 'arrow';
+export interface BreadcrumbItem {
+    /** Display text for the breadcrumb item */
+    label: string;
+    /** URL to navigate to (if not provided, item is not clickable) */
+    href?: string;
+    /** Optional icon to display before the label */
+    icon?: React.ReactNode;
+    /** Whether this is the current/active item */
+    current?: boolean;
+    /** Click handler for the breadcrumb item */
+    onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void;
+}
+export interface BreadcrumbProps extends React.HTMLAttributes<HTMLElement> {
+    /** Array of breadcrumb items */
+    items: BreadcrumbItem[];
+    /** Type of separator to use between items */
+    separator?: BreadcrumbSeparator;
+    /** Whether to show icons */
+    showIcons?: boolean;
+    /** Maximum number of items to show before truncating */
+    maxItems?: number;
+    /** Custom className */
+    className?: string;
+    /** Optional data-test-id attribute */
+    'data-test-id'?: string;
+}
+/**
+ * Breadcrumb component for navigation hierarchy display
+ *
+ * @example
+ * ```tsx
+ * <Breadcrumb
+ *   items={[
+ *     { label: 'Home', href: '/' },
+ *     { label: 'Products', href: '/products' },
+ *     { label: 'Shoes', current: true }
+ *   ]}
+ *   separator="slash"
+ * />
+ * ```
+ */
+export declare const Breadcrumb: React.ForwardRefExoticComponent<BreadcrumbProps & React.RefAttributes<HTMLElement>>;
+export default Breadcrumb;

package/dist/components/Breadcrumb/index.js

@@ -0,0 +1,136 @@
+import { jsx as n, jsxs as o, Fragment as B } from "react/jsx-runtime";
+import h, { forwardRef as F } from "react";
+import { cn as c } from "../../shared/utils/cn.js";
+import { dataTestId as S } from "../../shared/utils/dataTestId.js";
+import { Dropdown as j } from "../Dropdown/index.js";
+import { breadcrumbVariants as D, breadcrumbLinkVariants as g, breadcrumbItemVariants as w, breadcrumbSeparatorVariants as I } from "./variants.js";
+const L = F(
+  ({
+    items: l,
+    separator: i = "slash",
+    showIcons: u = !0,
+    maxItems: s,
+    className: N,
+    "data-test-id": v,
+    ...C
+  }, k) => {
+    const y = S("breadcrumb", v), { displayItems: m, hiddenItems: d } = h.useMemo(() => {
+      if (!s || l.length <= s)
+        return { displayItems: l, hiddenItems: [] };
+      const r = l[0], e = l.slice(-(s - 2)), a = l.slice(1, l.length - (s - 2));
+      return {
+        displayItems: [r, ...e],
+        hiddenItems: a
+      };
+    }, [l, s]), f = (r) => {
+      switch (r) {
+        case "slash":
+          return "/";
+        case "dot":
+          return "•";
+        case "arrow":
+          return ">";
+        default:
+          return "/";
+      }
+    }, p = (r, e) => {
+      const a = e === m.length - 1, t = r.current || a, b = /* @__PURE__ */ o(B, { children: [
+        u && r.icon && /* @__PURE__ */ n("span", { className: "w-4 h-4 flex-shrink-0", children: r.icon }),
+        /* @__PURE__ */ n("span", { children: r.label })
+      ] });
+      return /* @__PURE__ */ o(h.Fragment, { children: [
+        /* @__PURE__ */ n(
+          "li",
+          {
+            className: c(
+              w({ current: t })
+            ),
+            children: r.href && !t ? /* @__PURE__ */ n(
+              "a",
+              {
+                href: r.href,
+                onClick: r.onClick,
+                className: c(g()),
+                "aria-current": t ? "page" : void 0,
+                children: b
+              }
+            ) : /* @__PURE__ */ n("span", { "aria-current": t ? "page" : void 0, children: b })
+          }
+        ),
+        !a && /* @__PURE__ */ n(
+          "li",
+          {
+            className: c(I({ variant: i })),
+            "aria-hidden": "true",
+            children: f(i)
+          }
+        )
+      ] }, e);
+    }, V = () => {
+      if (d.length === 0) return null;
+      const r = d.map((e) => ({
+        value: e.href || e.label,
+        label: e.label,
+        icon: u && e.icon ? e.icon : void 0
+      }));
+      return /* @__PURE__ */ o(h.Fragment, { children: [
+        /* @__PURE__ */ n("li", { className: c(w({ current: !1 })), children: /* @__PURE__ */ n(
+          j,
+          {
+            items: r,
+            placeholder: "...",
+            onValueChange: (e) => {
+              const a = d.find(
+                (t) => (t.href || t.label) === e
+              );
+              if (a?.onClick && a.href) {
+                const t = new MouseEvent("click");
+                a.onClick(t);
+              } else a?.href && (window.location.href = a.href);
+            },
+            trigger: /* @__PURE__ */ n(
+              "button",
+              {
+                className: c(
+                  g(),
+                  "inline-flex items-center gap-1 px-2 py-1 text-sm"
+                ),
+                "aria-label": "Show hidden breadcrumb items",
+                children: /* @__PURE__ */ n("span", { children: "..." })
+              }
+            ),
+            side: "bottom",
+            align: "start"
+          }
+        ) }),
+        /* @__PURE__ */ n(
+          "li",
+          {
+            className: c(I({ variant: i })),
+            "aria-hidden": "true",
+            children: f(i)
+          }
+        )
+      ] }, "dropdown");
+    };
+    return /* @__PURE__ */ n(
+      "nav",
+      {
+        ref: k,
+        className: c(D({ className: N })),
+        "aria-label": "Breadcrumb",
+        "data-test-id": y,
+        ...C,
+        children: /* @__PURE__ */ n("ol", { className: "flex items-center flex-wrap gap-1", children: m.map((r, e) => e === 1 && d.length > 0 ? /* @__PURE__ */ o(h.Fragment, { children: [
+          V(),
+          p(r, e)
+        ] }, `item-${e}`) : p(r, e)) })
+      }
+    );
+  }
+);
+L.displayName = "Breadcrumb";
+export {
+  L as Breadcrumb,
+  L as default
+};

package/dist/components/Breadcrumb/variants.d.ts

@@ -0,0 +1,37 @@
+export declare const breadcrumbVariants: import('tailwind-variants').TVReturnType<{} | {} | {}, undefined, "flex items-center flex-wrap gap-1", {} | {}, undefined, import('tailwind-variants').TVReturnType<unknown, undefined, "flex items-center flex-wrap gap-1", unknown, unknown, undefined>>;
+export declare const breadcrumbItemVariants: import('tailwind-variants').TVReturnType<{
+    current: {
+        true: string;
+        false: string;
+    };
+}, undefined, string[], {
+    current: {
+        true: string;
+        false: string;
+    };
+}, undefined, import('tailwind-variants').TVReturnType<{
+    current: {
+        true: string;
+        false: string;
+    };
+}, undefined, string[], unknown, unknown, undefined>>;
+export declare const breadcrumbSeparatorVariants: import('tailwind-variants').TVReturnType<{
+    variant: {
+        slash: string;
+        dot: string;
+        arrow: string;
+    };
+}, undefined, string[], {
+    variant: {
+        slash: string;
+        dot: string;
+        arrow: string;
+    };
+}, undefined, import('tailwind-variants').TVReturnType<{
+    variant: {
+        slash: string;
+        dot: string;
+        arrow: string;
+    };
+}, undefined, string[], unknown, unknown, undefined>>;
+export declare const breadcrumbLinkVariants: import('tailwind-variants').TVReturnType<{} | {} | {}, undefined, string[], {} | {}, undefined, import('tailwind-variants').TVReturnType<unknown, undefined, string[], unknown, unknown, undefined>>;