mainstack-design-system 0.7.45 → 1.0.0

package/README.md

@@ -1,22 +1,707 @@
 <!--@@joggrdoc@@-->
 <!-- @joggr:version(v2):end -->
 <!-- @joggr:warning:start -->
-<!-- 
-  _   _   _    __        __     _      ____    _   _   ___   _   _    ____     _   _   _ 
+<!--
+  _   _   _    __        __     _      ____    _   _   ___   _   _    ____     _   _   _
  | | | | | |   \ \      / /    / \    |  _ \  | \ | | |_ _| | \ | |  / ___|   | | | | | |
  | | | | | |    \ \ /\ / /    / _ \   | |_) | |  \| |  | |  |  \| | | |  _    | | | | | |
  |_| |_| |_|     \ V  V /    / ___ \  |  _ <  | |\  |  | |  | |\  | | |_| |   |_| |_| |_|
  (_) (_) (_)      \_/\_/    /_/   \_\ |_| \_\ |_| \_| |___| |_| \_|  \____|   (_) (_) (_)
-                                                              
-This document is managed by Joggr. Editing this document could break Joggr's core features, i.e. our 
-ability to auto-maintain this document. Please use the Joggr editor to edit this document 
+
+This document is managed by Joggr. Editing this document could break Joggr's core features, i.e. our
+ability to auto-maintain this document. Please use the Joggr editor to edit this document
 (link at bottom of the page).
 -->
 <!-- @joggr:warning:end -->
+
 ## Storybook Documentation
 
 To view the design system documentation, visit this [link](https://mainstack-design-system.vercel.app/).
 
+# Design System Development Guide
+
+---
+
+## Design Tokens
+
+### Token Naming Convention
+
+All custom CSS variables must follow the `--ms-name-of-variable` pattern using kebab-case.
+
+```css
+/* ✅ Correct */
+--ms-primary-color: #3b82f6;
+--ms-text-base: 1rem;
+
+/* ❌ Incorrect */
+--primaryColor: #3b82f6;
+--ms_text_base: 1rem;
+```
+
+### Token Inference
+
+Tokens should be inferred directly from design documentation on Figma.
+
+---
+
+# Component Architecture
+
+## Composition Component Pattern Guide
+
+### Overview
+
+Our design system uses a composition architecture pattern that provides both **simple** and **advanced** APIs for components. This guide explains when and how to use each pattern.
+
+---
+
+## Pattern 1: Direct Composition (`Comp.Root`)
+
+**Use when:** The component requires multiple sub-components in most use cases.
+
+### Structure
+
+```tsx
+// Most common usage requires composition
+Dialog.Root;
+Dialog.Trigger;
+Dialog.Content;
+Dialog.Header;
+Dialog.Footer;
+
+DialogRoot;
+DialogTrigger;
+DialogContent;
+DialogHeader;
+DialogFooter;
+```
+
+### Example: Dialog Component
+
+```tsx
+//Dialog almost always needs multiple parts
+import { Dialog } from "@/components/dialog";
+
+<Dialog.Root open={open} onOpenChange={setOpen}>
+  <Dialog.Trigger asChild>
+    <button>Open Dialog</button>
+  </Dialog.Trigger>
+
+  <Dialog.Content>
+    <Dialog.Header>
+      <Dialog.Title>Confirm Action</Dialog.Title>
+    </Dialog.Header>
+
+    <p>Are you sure you want to continue?</p>
+
+    <Dialog.Footer>
+      <Dialog.Close asChild>
+        <button>Cancel</button>
+      </Dialog.Close>
+      <button>Confirm</button>
+    </Dialog.Footer>
+  </Dialog.Content>
+</Dialog.Root>;
+```
+
+```tsx
+// Tree shaking example
+import {
+  DialogRoot,
+  DialogTrigger,
+  DialogContent,
+  DialogHeader,
+  DialogFooter,
+} from "@/components/dialog";
+
+<DialogRoot open={open} onOpenChange={setOpen}>
+  <DialogTrigger asChild>
+    <button>Open Dialog</button>
+  </DialogTrigger>
+
+  <DialogContent>
+    <DialogHeader>
+      <Dialog.Title>Confirm Action</Dialog.Title>
+    </DialogHeader>
+
+    <p>Are you sure you want to continue?</p>
+
+    <DialogFooter>
+      <DialogClose asChild>
+        <button>Cancel</button>
+      </DialogClose>
+      <button>Confirm</button>
+    </DialogFooter>
+  </DialogContent>
+</DialogRoot>;
+```
+
+### When to Use
+
+- Component is **interactive** and requires multiple parts to function
+- **No simplified version** makes sense
+- Examples: Dialog, Dropdown, Accordion, Tabs,
+
+---
+
+## Pattern 2: Simple + Composition (`Comp` + `CompGroup.Root` or `CompRoot`)
+
+**Use when:** The component is **presentational** and typically only needs **one sub-component** (like a label), but can be extended with additional parts.
+
+### Structure
+
+```tsx
+// Simple component for common case
+Comp;
+
+// Composiition for tree shaking
+CompRoot;
+CompLabel;
+CompIcon;
+
+// Composition for advanced cases
+CompGroup.Root;
+CompGroup.Label;
+CompGroup.Icon;
+```
+
+### Example: Tag Component
+
+```tsx
+//  SIMPLE (80% of use cases)
+import { Tag } from '@/components/tag'
+
+<Tag>React</Tag>
+<Tag variant="success">Active</Tag>
+<Tag>TypeScript</Tag>
+
+//  ADVANCED with tree shaking (10% of use cases)
+import { TagRoot, TagIcon, TagLabel } from '@/components/tag'
+
+<TagRoot variant="success">
+  <TagIcon>
+    <Check className="h-3 w-3" />
+  </TagIcon>
+  <TagLabel>Verified User</TagLabel>
+</TagRoot>
+
+
+// ADVANCED import all composables (10% of use cases)
+import { TagGroup } from '@/components/tag'
+
+<TagGroup.Root variant="success">
+  <TagGroup.Icon>
+    <Check className="h-3 w-3" />
+  </TagGroup.Icon>
+  <TagGroup.Label>Verified User</TagGroup.Label>
+</TagGroup.Root>
+```
+
+### When to Use
+
+- Component is **presentational** (non-interactive by default)
+- **Most use cases** only need text/label
+- Can be extended with icons, badges, or other decorations
+- Examples: Tag, Button, Chip,
+
+---
+
+## Pattern 3: Single Component with Props
+
+**Use when:** The component has variations but doesn't need composition.
+
+### Structure
+
+```tsx
+// Single component with variants
+Avatar;
+```
+
+### Example: Button Component
+
+```tsx
+// ✅ Props handle all variations
+import { Avatar } from "@/components/Avatar";
+
+<Avatar variant="picture">Click me</Avatar>;
+```
+
+### When to Use
+
+- Component variations are handled by **props** (variant, size, state)
+- No need for multiple sub-components
+- Example: Avatar
+
+---
+
+#### Controlled vs Uncontrolled
+
+Components should support both controlled and uncontrolled usage for maximum flexibility.
+This can ba achieved with `@radix-ui/react-use-controllable-state`
+
+#### asChild Pattern
+
+**Default to `asChild` with Radix Slot for interactive components.**
+
+```tsx
+import { Slot } from "@radix-ui/react-slot";
+
+interface ButtonProps {
+  asChild?: boolean;
+  // other props
+}
+
+const Button = ({ asChild = false, ...props }: ButtonProps) => {
+  const Comp = asChild ? Slot : "button";
+  return <Comp {...props} />;
+};
+
+// Usage
+<Button asChild>
+  <a href="/home">Go Home</a>
+</Button>;
+```
+
+**Use `as` prop only for non-interactive primitives** (Typography, Tags, etc.)
+
+```tsx
+// ✅ Correct - Non-interactive primitive
+<Text as="h1">Heading</Text>
+<Text as="p">Paragraph</Text>
+
+// ❌ Incorrect - Interactive component
+<Button as="a" href="/home">Link</Button>  // Use asChild instead
+```
+
+---
+
+## Styling Conventions
+
+### Class Names
+
+**Always use kebab-case for class names.**
+
+```tsx
+// ✅ Correct
+className = "button-primary";
+className = "dialog-content";
+className = "form-field-error";
+
+// ❌ Incorrect
+className = "buttonPrimary";
+className = "DialogContent";
+className = "form_field_error";
+```
+
+Pass user classes and props last as overrides to variants and any other component styling.
+
+### State Management with data-state
+
+**Use `data-state` attributes for styling element states.**
+
+```tsx
+// Component
+<button
+  data-state={isOpen ? "open" : "closed"}
+  data-disabled={disabled}
+  data-loading={isLoading}
+>
+  {children}
+</button>
+
+// CSS/Tailwind
+<button
+  className="
+    data-[state=open]:opacity-50
+    data-[disabled]:cursor-not-allowed
+    data-[loading]:bg-primary
+  "
+>
+```
+
+### data-slot for Composition Styling
+
+**Use `data-slot` for styling specific parts in composition patterns.**
+
+```tsx
+// Component
+const Card = {
+  Root: ({ children }) => (
+    <div data-slot="root" className="card">
+      {children}
+    </div>
+  ),
+  Header: ({ children }) => (
+    <div data-slot="header" className="card-header">
+      {children}
+    </div>
+  ),
+  Body: ({ children }) => (
+    <div data-slot="body" className="card-body">
+      {children}
+    </div>
+  ),
+}
+
+// CSS targeting
+.card [data-slot="header"] {
+  /* Header-specific styles when inside card */
+}
+
+.card [data-slot="body"] {
+  /* Body-specific styles when inside card */
+}
+```
+
+# Client And Server Component Approach
+
+The design system is built on React 19 and as such component built should support SSR, Server component (if applicable) and Client Component. Please reference react doc [here](https://react.dev/reference/rsc/use-client#when-to-use-use-client) for more info.
+
+> **Please Note:** That SSR is different from React Server Component. This article [here](https://www.joshwcomeau.com/react/server-components/) explained it better.
+
+## Server Component Support
+
+The rule of thumb here is components with only styling, presentation component with no client-side interactivity, state management, context provider usage or browser APIs usage should be server compatible.
+
+So server component can't have `useState` or `useEffect` in them, hence why they are presentational component with styling alone.
+
+E.g Typograhy and Icon components; `DisplayText`, `BodyText` and `HeadlineText`
+
+> **Please Note:** This component should not be exported with the `use client` directives
+
+## Client Component Support And SSR
+
+The rule of thumb here is components with client-side interactivity, state management, context provider usage or browser APIs usage should be client compatible and as such have the `use client` directives.
+
+E.g `ImageUploader`, `Tooltip`
+
+> **Please Note:** This component should be exported with the `use client` directives
+
+That being said there are cases where Radix UI doesn't serve all your needs and you would need to build the component your self while keeping SSR in mind.
+
+- Avoid Browser-Specific APIs in Rendering Logic: Browser APIs like window, document, localStorage, or sessionStorage.
+- Always use `useEffect` hook for any side effect. Also use the `typeof window !== 'undefined'` to ensure browser-specific code only executes on the client.
+- Avoid Time-Dependent Logic: Do not use time-dependent APIs like `Date()` constructors in your rendering logic, as the server and client might render at slightly different times, causing a mismatch.
+
+While using the composition Component Pattern, only mark component as client with the `use client` directive on a per component level.
+
+**Example:**
+
+```tsx
+"use client";
+import { useState, useEffect } from "react";
+
+interface DialogRootProps {
+  // dialog props
+}
+
+export const DialogRoot = ({ asChild = false, ...props }: DialogRootProps) => {
+  const [dialogOpen, setDialogOpen] = useState();
+  const Comp = asChild ? Slot : "div";
+
+  useEffect(() => {
+    // Make some side effect
+  }, []);
+  return <Comp open={dialogOpen} onOpen={setDialogOpen} {...props} />;
+};
+```
+
+```tsx
+interface DialogBodyProps {
+  // dialog props
+}
+
+export const DialogBody = ({ asChild = false, ...props }: DialogBodyProps) => {
+  const Comp = asChild ? Slot : "div";
+  return <Comp open={dialogOpen} onOpen={setDialogOpen} {...props} />;
+};
+```
+
+```tsx
+import { DialogRoot, DialogBody } from "./dialog";
+
+const App = () => {
+  return (
+    <DialogRoot>
+      <DialogBody>// Your content</DialogBody>
+    </DialogRoot>
+  );
+};
+```
+
+In the example above `DialogBody` is a composable component that's meant to be used with `DialogRoot` but we only mark `DialogRoot` as client because it's using a state and an effect.
+
+If `DialogBody` and `DialogRoot` were imported into a React server component, `DialogBody` will render on the server while `DialogRoot` will render on client. This works as a result of react [module dependency tree](https://react.dev/reference/rsc/use-client#how-use-client-marks-client-code)
+
+Summary:
+
+- If the component uses any React State or context provider, mark as client.
+- If the component uses any Browser API, mark as client.
+
+---
+
+## Folder Structure
+
+### Component Organization
+
+**Every component must be in a named folder with barrel exports.**
+
+```
+src/components/Button/
+├── Button.tsx              # Main component
+├── Button.stories.tsx      # Storybook stories
+├── Button.test.tsx         # Tests
+├── useButton.ts           # Component-specific hook (if needed)
+├── buttonVariants.ts      # CVA variants (if needed)
+└── index.ts                # Barrel export
+
+src/components/Dialog/
+├── DialogRoot.tsx
+├── DialogTrigger.tsx
+├── DialogContent.tsx
+├── DialogHeader.tsx
+├── DialogFooter.tsx
+├── useDialog.ts           # Dialog-specific hook
+├── Dialog.stories.tsx
+├── Dialog.test.tsx
+└── index.ts                # Exports all parts
+```
+
+### Barrel Export Pattern
+
+```typescript
+// index.ts
+
+// single component
+export { Button } from "./Button";
+
+// Composition components
+export { ButtonRoot } from "./ButtonRoot";
+export type { ButtonRootProps } from "./ButtonRoot";
+
+export { ButtonIcon } from "./ButtonIcon";
+export type { ButtonIconProps } from "./ButtonIcon";
+
+export { ButtonLabel } from "./ButtonLabel";
+export type { ButtonLabelProps } from "./ButtonLabel";
+
+export { buttonVariants } from "./buttonVariants";
+
+// Composition object for dot notation usage
+import { ButtonRoot } from "./ButtonRoot";
+import { ButtonIcon } from "./ButtonIcon";
+import { ButtonLabel } from "./ButtonLabel";
+
+export const ButtonGroup = {
+  Root: ButtonRoot,
+  Icon: ButtonIcon,
+  Label: ButtonLabel,
+};
+
+// Composition without simple exported component
+import { AccordionRoot } from "./AccordionRoot";
+import { AccordionHeader } from "./AccordionHeader";
+import { AccordionTrigger } from "./AccordionTrigger";
+
+export const Accordion = {
+  Root: AccordionRoot,
+  Header: AccordionHeader,
+  Trigger: AccordionTrigger,
+};
+```
+
+### Tree Shaking Rules
+
+**Keep component-specific code colocated:**
+
+- ✅ Component-specific helpers → Stay in component folder
+- ✅ Component-specific hooks → Stay in component folder
+- ✅ Component-specific types → Stay in component folder
+
+**Move to shared when:**
+
+- ❌ Used in more than one component → Move to `src/utils/` or `src/hooks/`
+
+---
+
+## Documentation Standards
+
+### Storybook Stories
+
+**Every component must have:**
+
+1. **1-2 major variants stories** (immediately visible)
+2. **One example with changeable controls** for other variants
+
+```typescript
+import type { Meta, StoryObj } from "@storybook/react";
+import { Button } from "./button";
+
+const meta: Meta<typeof Button> = {
+  title: "Components/UI/Button",
+  component: Button,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof Button>;
+
+export const Primary: Story = {
+  args: {
+    children: "Primary Button",
+    variant: "primary",
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    children: "Secondary Button",
+    variant: "secondary",
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    children: "Primary Button",
+    variant: "primary",
+    size: "lg",
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    children: "Primary Button",
+    variant: "primary",
+    size: "md",
+  },
+};
+
+// All Other Variants - One example with controls
+export const Playground: Story = {
+  args: {
+    children: "Playground Button",
+  },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["primary", "secondary", "outline", "ghost", "destructive"],
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg"],
+    },
+    disabled: {
+      control: "boolean",
+    },
+  },
+};
+```
+
+---
+
+## Accessibility
+
+### Semantic HTML First
+
+**Always use semantic HTML elements as the foundation.**
+
+```tsx
+// ✅ Correct - Semantic HTML
+<button type="button">Click me</button>
+<nav>Navigation</nav>
+<main>Main content</main>
+<article>Article content</article>
+
+// ❌ Incorrect - Non-semantic
+<div onClick={handleClick}>Click me</div>
+<div>Navigation</div>
+<div>Main content</div>
+```
+
+### ARIA for Exceptions
+
+**Use ARIA attributes only when semantic HTML is insufficient.**
+
+```tsx
+// ✅ Correct - ARIA only when needed
+<div
+  role="button"
+  tabIndex={0}
+  aria-label="Close dialog"
+  onKeyDown={handleKeyDown}
+>
+  <CloseIcon />
+</div>
+
+// ✅ Correct - Complex widget states
+<button
+  aria-expanded={isOpen}
+  aria-controls="menu-content"
+  aria-haspopup="true"
+>
+  Menu
+</button>
+
+// ❌ Incorrect - Unnecessary ARIA
+<button aria-label="Submit">Submit</button>  // Text already visible
+```
+
+### Accessibility Checklist
+
+- ✅ Keyboard navigation support
+- ✅ Focus management
+- ✅ Screen reader announcements
+- ✅ Color contrast (WCAG AA minimum)
+- ✅ Touch target sizes (minimum 44x44px)
+- ✅ Reduced motion support
+
+---
+
+## API Design
+
+### Prop Naming
+
+**Ensure prop names don't clash with HTML attributes except where explicitly needed to override.**
+
+```tsx
+// ✅ Correct - No clash
+interface ButtonProps {
+  variant?: "primary" | "secondary";
+  isLoading?: boolean; // Not "loading" (clashes with HTML)
+}
+
+// ✅ Correct - Intentional override
+interface InputProps {
+  type?: "text" | "email" | "password"; // Override HTML type
+  disabled?: boolean; // Override HTML disabled
+}
+
+// ❌ Incorrect - Unintentional clash
+interface CustomInputProps {
+  value?: string; // Clashes with HTML value
+  name?: string; // Clashes with HTML name
+  // Should use different names or explicitly document override
+}
+```
+
+---
+
+## Contributing
+
+When contributing new components:
+
+1. Follow this guide
+2. Include comprehensive Storybook documentation
+3. Ensure TypeScript types are exported
+4. Test controlled and uncontrolled modes
+5. Verify keyboard navigation
+6. Check responsive behavior
+7. Submit with visual regression tests
+
+<!-- v0 Documentation-->
+
 # Usage
 
 Install the design system
@@ -28,9 +713,9 @@ Add the Design system provider to your root file
 ```typescript
 import { MainstackProvider } from "mainstack-design-system";
 
- <MainstackProvider>
-  <App/>
-</MainstackProvider>
+<MainstackProvider>
+  <App />
+</MainstackProvider>;
 ```
 
 ## Components
@@ -50,40 +735,40 @@ Icons are imported from the `'mainstack-design-system` directory. For example:
 Colors are imported from the `mainstack-design-system` directory. For example:
 
 ```typescript
- import {Colors} from "mainstack-design-system";
+import { Colors } from "mainstack-design-system";
 
- <Text color={Colors.black300}>Hello World</Text>
+<Text color={Colors.black300}>Hello World</Text>;
 ```
 
 ## Contributing
 
 Installing the application (as a developer) is simple in the following steps:
 
-* Access and Clone this repository
+- Access and Clone this repository
 
 ```shell
 git clone git clone https://github.com/The-Mainstack/mainstack-design-system.git && cd [repo-name]
 ```
 
-* Make your forked repo the remote upstream (at origin)
+- Make your forked repo the remote upstream (at origin)
 
 ```shell
 git remote add origin https://github.com/The-Mainstack/mainstack-design-system.git
 ```
 
-* Navigate into the cloned directory and install dependencies with Yarn
+- Navigate into the cloned directory and install dependencies with Yarn
 
 ```typescript
 yarn add
 ```
 
-* Make a duplicate of the **env** file and update its content accordingly. Most times, this is just fine with no update.
+- Make a duplicate of the **env** file and update its content accordingly. Most times, this is just fine with no update.
 
 ```shell
 cp .env.sample .env
 ```
 
-* Run the app in the development mode. Open [http://localhost:\[port\]](http://localhost:%5Bport%5D) to view it in the browser and start developing.
+- Run the app in the development mode. Open [http://localhost:\[port\]](http://localhost:%5Bport%5D) to view it in the browser and start developing.
 
 ```typescript
 yarn dev
@@ -102,7 +787,9 @@ To Publish to NPM, run the following command:
 ```
 
 <!-- @joggr:editLink(b428f959-2d9d-45aa-8134-1d4f284d1469):start -->
+
 ---
+
 <a href="https://app.joggr.io/app/documents/b428f959-2d9d-45aa-8134-1d4f284d1469/edit">
   <img src="https://cdn.joggr.io/assets/static/badges/joggr-document-edit.svg?did=b428f959-2d9d-45aa-8134-1d4f284d1469" alt="Edit doc on Joggr" />
 </a>