@tap-payments/os-micro-frontend-shared 0.1.491 → 0.1.492-test.2

package/docs/05-component-development.md

@@ -0,0 +1,173 @@
+# Building Components
+
+How to create new components, follow conventions, and wire them into the library. **Check the [Component Guide](./04-component-guide.md) first** to avoid duplicating existing components.
+
+## Table of Contents
+
+1. [Component Folder Structure](#component-folder-structure) - File layout for a new component
+2. [Export Chain](#export-chain) - How exports flow to consumers
+3. [Conventions & Patterns](#conventions--patterns) - DO/DON'T and code patterns
+4. [Component Template](#component-template) - Standard component structure
+5. [Styling & Types](#styling--types) - style.ts and types.ts patterns
+6. [Decision Tree](#decision-tree) - Structure, imports, exports, styling
+7. [Quick Task Reference](#quick-task-reference) - Common development tasks
+
+## Component Folder Structure
+
+Each component lives in its own folder under `src/components/[Name]/`:
+
+```
+src/components/[ComponentName]/
+├── index.ts         # Public exports (named + default)
+├── [ComponentName].tsx   # Main React component
+├── style.ts         # Emotion styled components
+└── types.ts         # Props and related interfaces
+```
+
+Optional: add `helper.ts`, `utils.ts`, or subcomponents in the same folder as needed. Keep the public API in `index.ts`.
+
+## Export Chain
+
+```mermaid
+flowchart TD
+  A["Component/index.ts"] --> B["components/index.ts"]
+  B --> C["src/index.ts"]
+  C --> D["build/"]
+  B["Named/default exports aggregated"] --> C
+  A["Public exports only"] --> B
+```
+
+Steps to expose a new component to consumers:
+
+1. Implement the component in `src/components/[Name]/` with `index.ts`, `[Name].tsx`, `types.ts`, `style.ts`.
+2. Export the component from `src/components/[Name]/index.ts` (default + named types).
+3. Re-export from `src/components/index.ts`.
+4. Run `yarn ts:build`; the build output in `build/` reflects the same structure.
+
+Consumers then import from the package (e.g. `@tap-payments/os-micro-frontend-shared` or `/components/Button`), not from path aliases.
+
+## Conventions & Patterns
+
+### Component Patterns
+
+**DO:**
+
+- Use `React.memo()` for performance where appropriate
+- Name props interface `[Component]Props` or `[Component]I`
+- Put styled components in a separate `style.ts`
+- Export from `index.ts` with both named (types/helpers) and default (component) exports
+- Use `@mui/material` base components
+
+**DON'T:**
+
+- Use inline styles; use Emotion/styled components
+- Use class components; use function components only
+- Export internal helpers that are not part of the public API from the main package
+
+### Export Pattern
+
+```typescript
+// Component/index.ts - Standard pattern
+import ComponentName from './ComponentName'
+
+export { SomeHelper } from './helper'
+export type { ComponentNameProps } from './types'
+
+export default ComponentName
+```
+
+## Component Template
+
+```typescript
+// [Name].tsx
+import { memo } from 'react'
+import { StyledWrapper } from './style'
+import type { MyComponentProps } from './types'
+
+function MyComponent({ children, ...props }: MyComponentProps) {
+  return <StyledWrapper {...props}>{children}</StyledWrapper>
+}
+
+export default memo(MyComponent)
+```
+
+## Styling & Types
+
+### Styling Pattern (style.ts)
+
+```typescript
+// style.ts - Standard pattern
+import { styled } from '@mui/material/styles'
+
+export const StyledComponent = styled('div')(({ theme }) => ({
+  backgroundColor: theme.palette.background.paper,
+  borderRadius: theme.shape.borderRadius,
+  padding: theme.spacing(2),
+}))
+```
+
+Use theme tokens (palette, typography, spacing, shape) so the component respects the app theme.
+
+### Type Definition Pattern (types.ts)
+
+```typescript
+// types.ts
+export interface MyComponentProps {
+  children?: React.ReactNode
+  variant?: 'primary' | 'secondary'
+  disabled?: boolean
+  onClick?: () => void
+}
+```
+
+Export only the types that consumers need; keep internal types in the same file or a separate internal type file if needed.
+
+## Decision Tree
+
+```mermaid
+flowchart TD
+  Q[How should I structure my component?]
+  Q --> A[Component folder structure]
+  Q --> B[How to import in source?]
+  Q --> C[How to export for consumers?]
+  Q --> D[How do consumers import?]
+  Q --> E[How to style?]
+
+  A --> A1["src/components/[Name]/"]
+  A1 --> A2["index.ts, [Name].tsx, types.ts, style.ts"]
+
+  B --> B1["Path aliases: @components, @utils, @types, etc."]
+
+  C --> C1["Add to module index e.g. src/components/index.ts"]
+
+  D --> D1["From package: '@tap-payments/os-micro-frontend-shared'"]
+
+  E --> E1["Emotion styled() with theme tokens"]
+```
+
+| Question | Answer |
+|----------|--------|
+| Component folder structure | `src/components/[Name]/` with `index.ts`, `[Name].tsx`, `types.ts`, `style.ts` |
+| How to import in source code? | Use path aliases: `@components`, `@utils`, `@types`, etc. |
+| How to export for consumers? | Add to the module `index.ts` (e.g. `src/components/index.ts`) |
+| How do consumers import? | From the package: `@tap-payments/os-micro-frontend-shared` or `/components/ComponentName` |
+| How to style components? | Use Emotion `styled()` with theme tokens |
+
+## Quick Task Reference
+
+| Task | Steps |
+|------|--------|
+| **Find a component** | Search in `src/components/[ComponentName]/`; check `src/components/index.ts` for exports |
+| **Understand a component** | Read `[ComponentName].tsx` for logic, `types.ts` for props, `style.ts` for styling |
+| **Add new component** | Create `src/components/[Name]/` with `[Name].tsx`, `index.ts`, `types.ts`, `style.ts`; export from `src/components/index.ts`; follow patterns in this guide |
+| **Debug import error** | Check `package.json` exports; verify path matches exports; confirm component is exported in the right `index.ts` |
+| **Modify theme** | Edit `src/theme/palette.ts` (colors), `src/theme/typography.ts` (fonts), `src/theme/components.ts` (MUI overrides) |
+| **Add utility function** | Add to the appropriate `src/utils/[category].ts`; export from `src/utils/index.ts`; add TypeScript types |
+
+---
+
+## Next Steps
+
+- [Component Guide](./04-component-guide.md) - Catalog of existing components and how to choose them (avoid duplication)
+- [Architecture](./03-architecture.md) - Package structure, build system, path aliases
+- [Setup Guide](./02-setup.md) - Development and build commands

package/docs/README.md

@@ -0,0 +1,38 @@
+# OS Micro Frontend Shared - Documentation
+
+Complete documentation for understanding and using the @tap-payments/os-micro-frontend-shared library. Designed for developers and AI assistants.
+
+## Table of Contents
+
+1. [Overview](./01-overview.md) - Project purpose, goals, and key features
+2. [Setup Guide](./02-setup.md) - Installation, development workflows, and CI/CD
+3. [Architecture](./03-architecture.md) - System architecture and design decisions
+4. [Component Guide](./04-component-guide.md) - Component catalog, selection, and avoiding duplication
+5. [Building Components](./05-component-development.md) - How to create new components and follow patterns
+
+## Quick Links
+
+- **Getting Started**: [Setup Guide](./02-setup.md) for installation and commands
+- **System Design**: [Architecture](./03-architecture.md) for understanding the structure
+- **Using Components**: [Component Guide](./04-component-guide.md) for component catalog and selection
+- **Creating Components**: [Building Components](./05-component-development.md) for new component steps and patterns
+- **Project Goals**: [Overview](./01-overview.md) for context and features
+
+## Project Structure
+
+```
+os-micro-frontend-shared/
+├── src/                       # Source code
+│   ├── components/            # UI components (100+)
+│   ├── hooks/                 # Custom React hooks (18)
+│   ├── utils/                 # Utility functions (47)
+│   ├── types/                 # TypeScript definitions (37)
+│   ├── constants/             # Constants and configs (41)
+│   ├── theme/                 # MUI theme configuration
+│   ├── demo/                  # Development examples
+│   └── index.ts               # Main entry point
+├── build/                     # Compiled output (ESM)
+└── docs/                      # This documentation
+```
+
+**Version**: 1.0.0 | **Updated**: Feb 2026

package/docs/stories/components/Accordion.stories.tsx

@@ -0,0 +1,302 @@
+import { useState } from 'react'
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import Box from '@mui/material/Box'
+import Typography from '@mui/material/Typography'
+import Accordion from '@components/Accordion'
+import type { AccordionProps } from '@components/Accordion/types'
+import { StoryTable, StoryThead, StoryTbody, StoryRow, StoryHeaderCell, StoryRowLabel, StoryCell, StoryHint } from '@storybook-utils'
+
+const baseContent = (
+  <Box sx={{ p: 2 }}>
+    <Typography variant="body2" color="text.secondary">
+      This is accordion body content. Use this area for forms, details, or grouped actions.
+    </Typography>
+  </Box>
+)
+
+const meta: Meta<typeof Accordion> = {
+  title: 'Components/Accordion',
+  component: Accordion,
+  tags: ['autodocs'],
+  argTypes: {
+    expanded: { table: { disable: true } },
+    onChange: { table: { disable: true } },
+    label: { control: 'text' },
+    content: { table: { disable: true } },
+    labelStartAdornment: { table: { disable: true } },
+    labelEndAdornment: { table: { disable: true } },
+    slotProps: { table: { disable: true } },
+    expandIcon: { table: { disable: true } },
+    disabled: { control: 'boolean' },
+  },
+  parameters: {
+    layout: 'padded',
+    controls: { expanded: true },
+  },
+  decorators: [
+    (Story) => (
+      <Box sx={{ maxWidth: 640, mx: 'auto', width: '100%' }}>
+        <Story />
+      </Box>
+    ),
+  ],
+}
+
+export default meta
+
+type Story = StoryObj<typeof Accordion>
+
+function BaseRender(args: Partial<AccordionProps>) {
+  const [expanded, setExpanded] = useState(false)
+
+  return (
+    <Accordion
+      expanded={expanded}
+      onChange={setExpanded}
+      label={args.label || 'Section title'}
+      content={baseContent}
+      disabled={args.disabled}
+      slotProps={args.slotProps}
+      labelStartAdornment={args.labelStartAdornment}
+      labelEndAdornment={args.labelEndAdornment}
+      expandIcon={args.expandIcon}
+    />
+  )
+}
+
+export const Base: Story = {
+  render: BaseRender,
+  args: {
+    label: 'Section title',
+    disabled: false,
+  },
+  parameters: {
+    docs: {
+      source: {
+        language: 'tsx',
+        code: `
+const [expanded, setExpanded] = useState(false)
+
+<Accordion
+  expanded={expanded}
+  onChange={setExpanded}
+  label="Section title"
+  content={<Box sx={{ p: 2 }}>...</Box>}
+/>
+        `.trim(),
+      },
+    },
+  },
+}
+
+function DefaultExpandedRender() {
+  const [expanded, setExpanded] = useState(true)
+
+  return (
+    <Accordion
+      expanded={expanded}
+      onChange={setExpanded}
+      label="Initially expanded"
+      content={baseContent}
+      labelEndAdornment={<Typography variant="caption">3 items</Typography>}
+    />
+  )
+}
+
+export const DefaultExpanded: Story = {
+  name: 'default expanded',
+  render: DefaultExpandedRender,
+  parameters: {
+    docs: {
+      source: {
+        language: 'tsx',
+        code: `
+const [expanded, setExpanded] = useState(true)
+
+<Accordion
+  expanded={expanded}
+  onChange={setExpanded}
+  label="Initially expanded"
+  content={<Box sx={{ p: 2 }}>...</Box>}
+  labelEndAdornment={<Typography variant="caption">3 items</Typography>}
+/>
+        `.trim(),
+      },
+    },
+  },
+}
+
+function WithAdornmentsRender() {
+  const [expanded, setExpanded] = useState(false)
+
+  return (
+    <Accordion
+      expanded={expanded}
+      onChange={setExpanded}
+      label="Filters"
+      labelStartAdornment={<Box component="span">F</Box>}
+      labelEndAdornment={<Typography variant="caption">Updated now</Typography>}
+      content={
+        <Box sx={{ p: 2, display: 'grid', gap: 1 }}>
+          <Typography variant="body2" color="text.secondary">
+            Status: Paid
+          </Typography>
+          <Typography variant="body2" color="text.secondary">
+            Region: GCC
+          </Typography>
+        </Box>
+      }
+    />
+  )
+}
+
+export const WithAdornments: Story = {
+  name: 'with adornments',
+  render: WithAdornmentsRender,
+  parameters: {
+    docs: {
+      source: {
+        language: 'tsx',
+        code: `
+const [expanded, setExpanded] = useState(false)
+
+<Accordion
+  expanded={expanded}
+  onChange={setExpanded}
+  label="Filters"
+  labelStartAdornment={<Box component="span">F</Box>}
+  labelEndAdornment={<Typography variant="caption">Updated now</Typography>}
+  content={<Box sx={{ p: 2 }}>...</Box>}
+/>
+        `.trim(),
+      },
+    },
+  },
+}
+
+function DisabledRender() {
+  const [expanded, setExpanded] = useState(false)
+
+  return (
+    <Accordion
+      expanded={expanded}
+      onChange={setExpanded}
+      disabled
+      label="Disabled section"
+      content={
+        <Box sx={{ p: 2 }}>
+          <Typography variant="body2">This section is not interactive while disabled.</Typography>
+        </Box>
+      }
+    />
+  )
+}
+
+export const Disabled: Story = {
+  render: DisabledRender,
+  parameters: {
+    docs: {
+      source: {
+        language: 'tsx',
+        code: `
+const [expanded, setExpanded] = useState(false)
+
+<Accordion
+  expanded={expanded}
+  onChange={setExpanded}
+  disabled
+  label="Disabled section"
+  content={<Box sx={{ p: 2 }}>...</Box>}
+/>
+        `.trim(),
+      },
+    },
+  },
+}
+
+const tableColumns = ['VARIANT', 'PREVIEW'] as const
+
+function AllVariantsRender() {
+  const [expandedRows, setExpandedRows] = useState({
+    collapsed: false,
+    expanded: true,
+    noArrow: false,
+    disabled: false,
+  })
+
+  return (
+    <Box sx={{ maxWidth: 960, mx: 'auto' }}>
+      <StoryTable>
+        <StoryThead>
+          <StoryRow>
+            {tableColumns.map((header, index) => (
+              <StoryHeaderCell key={header} first={index === 0}>
+                {header}
+              </StoryHeaderCell>
+            ))}
+          </StoryRow>
+        </StoryThead>
+
+        <StoryTbody>
+          <StoryRow>
+            <StoryRowLabel>Collapsed</StoryRowLabel>
+            <StoryCell sx={{ width: '75%' }}>
+              <Accordion
+                expanded={expandedRows.collapsed}
+                onChange={(next) => setExpandedRows((prev) => ({ ...prev, collapsed: next }))}
+                label="Collapsed accordion"
+                content={baseContent}
+              />
+            </StoryCell>
+          </StoryRow>
+
+          <StoryRow>
+            <StoryRowLabel>Expanded</StoryRowLabel>
+            <StoryCell sx={{ width: '75%' }}>
+              <Accordion
+                expanded={expandedRows.expanded}
+                onChange={(next) => setExpandedRows((prev) => ({ ...prev, expanded: next }))}
+                label="Expanded accordion"
+                content={baseContent}
+              />
+            </StoryCell>
+          </StoryRow>
+
+          <StoryRow>
+            <StoryRowLabel>No Arrow</StoryRowLabel>
+            <StoryCell sx={{ width: '75%' }}>
+              <Accordion
+                expanded={expandedRows.noArrow}
+                onChange={(next) => setExpandedRows((prev) => ({ ...prev, noArrow: next }))}
+                label="Arrow hidden via slot props"
+                content={baseContent}
+                slotProps={{ label: { showArrow: false } }}
+              />
+            </StoryCell>
+          </StoryRow>
+
+          <StoryRow>
+            <StoryRowLabel>Disabled</StoryRowLabel>
+            <StoryCell sx={{ width: '75%' }}>
+              <Accordion
+                expanded={expandedRows.disabled}
+                onChange={(next) => setExpandedRows((prev) => ({ ...prev, disabled: next }))}
+                label="Disabled accordion"
+                content={baseContent}
+                disabled
+              />
+            </StoryCell>
+          </StoryRow>
+        </StoryTbody>
+      </StoryTable>
+
+      <StoryHint>Each row is independently controllable. Click labels to toggle expansion.</StoryHint>
+    </Box>
+  )
+}
+
+export const AllVariants: Story = {
+  name: 'all variants',
+  decorators: [],
+  render: AllVariantsRender,
+}