mainstack-design-system 1.1.2 → 1.2.1

package/README.md

@@ -14,790 +14,47 @@ ability to auto-maintain this document. Please use the Joggr editor to edit this
 -->
 <!-- @joggr:warning:end -->
 
-## Storybook Documentation
+## Documentation
 
-To view the design system documentation, visit this [link](https://mainstack-design-system.vercel.app/).
+You can find the Mainstack-Design-System documentation [here](https://design.mainstack.co/).
 
-## 🔧 Utilities & Helpers Reference
+## Examples
 
-**Before building, check what's already available to avoid rebuilding existing functionality:**
-
-- **[UTILITIES.md](./UTILITIES.md)** - Utility functions, hooks, and types (4 min read)
-
-The design system includes many utilities that don't map to Figma:
-
-- **Helper functions**: `cn()`, `sanitizeNumberInputValue()`, `formatPriceDigit()`
-- **Hooks**: `useElementWidth()`, `useMainstackDesignSystemTheme()`
-- **Provider**: `MainstackDesignSystemProvider` (theme management)
-- **Type utilities**: `PolymorphicProps`, `CountryIso2CodeType`
-
-# 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
+We have several examples [on the storybook doc](https://design.mainstack.co/). Here is the first one to get you started:
 
 ```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
-}
+  SelectRoot,
+  SelectPortal,
+  SelectOptions,
+  SelectOptionItem,
+} from "mainstack-design-system";
+
+export default () => (
+  <FormItem>
+    <FormLabel>Label</FormLabel>
+    <Select {...args}>
+      <SelectOptions>
+        {({ options }) =>
+          options.map((option) => (
+            <SelectOptionItem key={option.value} value={option.value}>
+              {option.label}
+            </SelectOptionItem>
+          ))
+        }
+      </SelectOptions>
+    </Select>
+    <FormSuccessStatus>Success message</FormSuccessStatus>
+  </FormItem>
+);
 ```
 
----
-
 ## 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
-
-`yarn add mainstack-design-system`
-
-Add the Design system provider to your root file
-
-```typescript
-import { MainstackProvider } from "mainstack-design-system";
-
-<MainstackProvider>
-  <App />
-</MainstackProvider>;
-```
-
-## Components
+Read our [Contributing Guide](https://github.com/The-Mainstack/mainstack-design-system/blob/v1/CONTRIBUTING.md).
 
-Components can be used by importing from the `'mainstack-design-system` directory. For example:
-
-`import { Button } from 'mainstack-design-system';`
-
-## Icons
-
-Icons are imported from the `'mainstack-design-system` directory. For example:
-
-`import { ArrowRightIcon } from 'mainstack-design-system';`
-
-## Colors
-
-Colors are imported from the `mainstack-design-system` directory. For example:
-
-```typescript
-import { Colors } from "mainstack-design-system";
-
-<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
-
-```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)
-
-```shell
-git remote add origin https://github.com/The-Mainstack/mainstack-design-system.git
-```
-
-- 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.
-
-```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.
-
-```typescript
-yarn dev
-```
-
-To run storybook, run the following command:
-
-```typescript
-yarn storybook
-```
-
-To Publish to NPM, run the following command:
-
-```typescript
- npm publish --access public
-```
+This project’s **Contributing Guide** also acts as our **Design System Development Guide**.  
+It outlines the standards, workflows, naming conventions, and component principles that keep the Design System consistent, scalable, and easy for everyone to build on. Before you begin, please take a moment to read through it so your work aligns with our shared practices.
 
 <!-- @joggr:editLink(b428f959-2d9d-45aa-8134-1d4f284d1469):start -->