cleanplate 0.1.7 → 0.1.8

package/docs/Typography.md

@@ -0,0 +1,226 @@
+# Typography Component
+
+Purpose: Provides a consistent set of text styles for headings, paragraphs, and inline elements, ensuring clear hierarchy, readability, and brand-aligned communication across the interface.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| children | React.ReactNode | no | — | Text content to display. |
+| variant | "h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6" \| "p" \| "span" \| "small" | no | "p" | HTML element type to render. Determines the semantic meaning and default styling. |
+| margin | string \| string[] | no | "m-0" | Spacing utility token(s), such as `m-0` or `["m-1", "m-b-2"]`. |
+| className | string | no | "" | Additional class names for the root element. |
+| isBold | boolean | no | false | Applies bold font weight to the text. |
+| align | "left" \| "center" \| "right" | no | "left" | Text alignment within its container. |
+| wordBreak | "normal" \| "all" \| "wrap" | no | "normal" | Controls how words break when text overflows. |
+| ...rest | any | no | — | All other standard HTML attributes are supported and passed through to the rendered element. |
+
+## Types
+
+### TypographyVariant
+```typescript
+type TypographyVariant = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span" | "small";
+```
+
+### TypographyAlign
+```typescript
+type TypographyAlign = "left" | "right" | "center";
+```
+
+### TypographyWordBreak
+```typescript
+type TypographyWordBreak = "normal" | "all" | "wrap";
+```
+
+### TypographyMargin
+```typescript
+type TypographyMargin = string | SpacingOption[];
+```
+
+### SpacingOption
+```typescript
+type SpacingOption = typeof SPACING_OPTIONS[number];
+```
+
+### TypographyProps
+```typescript
+interface TypographyProps {
+  children?: React.ReactNode;
+  variant?: TypographyVariant;
+  margin?: TypographyMargin;
+  className?: string;
+  isBold?: boolean;
+  align?: TypographyAlign;
+  wordBreak?: TypographyWordBreak;
+  [key: string]: any; // Allow other HTML attributes to be passed through
+}
+```
+
+## Usage Examples
+
+### Headings
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Typography variant="h1">Heading 1</Typography>
+    <Typography variant="h2">Heading 2</Typography>
+    <Typography variant="h3">Heading 3</Typography>
+    <Typography variant="h4">Heading 4</Typography>
+    <Typography variant="h5">Heading 5</Typography>
+    <Typography variant="h6">Heading 6</Typography>
+  </>
+);
+```
+
+### Paragraph (default)
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <Typography>
+    This is a paragraph. When no variant is specified, it defaults to a paragraph element.
+  </Typography>
+);
+```
+
+### Small text
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <Typography variant="small">
+    This is small text, typically used for captions or fine print.
+  </Typography>
+);
+```
+
+### Inline span
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <Typography variant="span">
+    This text is rendered as an inline span element.
+  </Typography>
+);
+```
+
+### Text alignment
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Typography align="left">Left aligned text</Typography>
+    <Typography align="center">Center aligned text</Typography>
+    <Typography align="right">Right aligned text</Typography>
+  </>
+);
+```
+
+### Bold text
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Typography>Normal weight text</Typography>
+    <Typography isBold>Bold text</Typography>
+  </>
+);
+```
+
+### Word breaking
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Typography wordBreak="normal">
+      Normal word breaking behavior
+    </Typography>
+    <Typography wordBreak="all">
+      Break words at any point if needed
+    </Typography>
+    <Typography wordBreak="wrap">
+      Wrap text with word breaking
+    </Typography>
+  </>
+);
+```
+
+### With margin spacing
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <>
+    <Typography variant="h1" margin="m-2">
+      Heading with margin
+    </Typography>
+    <Typography margin={["m-1", "m-b-3"]}>
+      Paragraph with multiple margins
+    </Typography>
+  </>
+);
+```
+
+### Combined properties
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <Typography
+    variant="h2"
+    isBold
+    align="center"
+    margin="m-4"
+  >
+    Centered, bold heading with margin
+  </Typography>
+);
+```
+
+### With HTML attributes
+
+```jsx
+import { Typography } from "cleanplate";
+
+export const Example = () => (
+  <Typography
+    variant="p"
+    id="description"
+    data-testid="typography-description"
+    aria-label="Product description"
+  >
+    This paragraph has additional HTML attributes.
+  </Typography>
+);
+```
+
+## Behavior Notes
+
+- When no `variant` is specified, the component defaults to rendering a `<p>` (paragraph) element.
+- The `variant` prop determines both the HTML element type (h1, h2, p, etc.) and the default styling applied.
+- The component uses semantic HTML elements, which is important for accessibility and SEO.
+- All standard HTML attributes can be passed through via the spread operator (`...rest`), allowing for custom `id`, `data-*`, `aria-*`, and other attributes.
+- The `align` prop controls text alignment using CSS classes, not inline styles.
+- The `wordBreak` prop provides control over how text wraps when it exceeds container width.
+- Margin spacing accepts either a single string token (e.g., `"m-2"`) or an array of tokens (e.g., `["m-1", "m-b-3"]`).
+- The `isBold` prop applies bold font weight, which can be combined with any variant.
+
+## Related Components / Links
+
+- Container (often used to wrap typography content)
+- MediaObject (commonly uses Typography for text content)

package/docs-template-sample.md

@@ -0,0 +1,67 @@
+# Avatar Component
+
+Purpose: Display a user avatar as an image, icon, or initials.
+
+## Props / Inputs
+
+| Prop | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| name | string | no | "" | Used for initials, title text, and background color seed. |
+| image | string | no | "" | Image URL to render when `icon` is not set. |
+| icon | string | no | "" | Icon name to render when `image` is not set. |
+| size | "small" \| "medium" | no | "medium" | Size variant. |
+| margin | string \| string[] | no | "m-0" | Spacing utility token(s), such as `m-0` or `m-b-2`. |
+| className | string | no | "" | Additional class names for the root element. |
+| onClick | function | no | — | Called with the click event. |
+
+## Types
+
+None.
+
+## Usage Examples
+
+### Initials (default)
+
+```jsx
+import { Avatar } from "cleanplate";
+
+export const Example = () => (
+  <Avatar name="Jane Doe" />
+);
+```
+
+### Image avatar
+
+```jsx
+import { Avatar } from "cleanplate";
+
+export const Example = () => (
+  <Avatar
+    name="Jane Doe"
+    image="https://example.com/jane.jpg"
+    size="small"
+  />
+);
+```
+
+### Icon avatar
+
+```jsx
+import { Avatar } from "cleanplate";
+
+export const Example = () => (
+  <Avatar icon="person" />
+);
+```
+
+## Behavior Notes
+
+- Initials are derived from the first letter of each word and limited to 2 characters.
+- Background color is generated from `name`, so the same name yields the same color.
+- Provide only one of `image` or `icon`. If both are set, the component renders no content.
+- The root element sets `title` to the value of `name`.
+
+## Related Components / Links
+
+- MediaObject
+- Icon

package/llms.txt

@@ -0,0 +1,76 @@
+# CleanPlate Component Documentation Index
+
+This file contains an index of all available component documentation for the CleanPlate UI framework.
+
+## Project Overview
+
+CleanPlate is a Headless React UI Framework providing reusable, accessible, and customizable components for building modern web applications.
+
+## Component Documentation
+
+All component documentation is located in the `docs/` folder. The following documentation files are available:
+
+### Button Component
+- File: `docs/Button.md`
+- Purpose: A highly customizable and interactive UI element designed to handle user actions with various styles, sizes, and variants. Supports loading states, disabled states, and click events.
+- Key Features: Variants (solid, outline, ghost, icon), sizes (small, medium), loading states, disabled states, fluid layout, margin spacing
+- Types: ButtonProps, ButtonSize, ButtonVariant, ButtonMargin, SpacingOption
+
+### Typography Component
+- File: `docs/Typography.md`
+- Purpose: Provides a consistent set of text styles for headings, paragraphs, and inline elements, ensuring clear hierarchy, readability, and brand-aligned communication across the interface.
+- Key Features: Variants (h1-h6, p, span, small), text alignment, word breaking, bold text, margin spacing
+- Types: TypographyProps, TypographyVariant, TypographyAlign, TypographyWordBreak, TypographyMargin, SpacingOption
+
+### Icon Component
+- File: `docs/Icon.md`
+- Purpose: A versatile and reusable element for displaying scalable vector icons, supporting various sizes, colors, and custom classes. Uses Google Material Symbols.
+- Key Features: Material Symbols integration, sizes (small, medium, large), colors (black, white, gray, blue, green, red, yellow, orange)
+- Types: IconProps, IconSize, IconColor
+- Note: Requires Material Symbols font to be included in the project
+
+### MediaObject Component
+- File: `docs/MediaObject.md`
+- Purpose: A flexible layout pattern that combines media (icon, image, or avatar) with content (title and description). Perfect for displaying user profiles, product cards, notifications, and any content that needs a media element alongside text.
+- Key Features: Media types (icon, image, avatar), title and description, margin and padding spacing, clickable support
+- Types: MediaObjectProps, MediaObjectMargin, MediaObjectPadding, SpacingOption
+- Related Components: Uses Avatar and Typography internally
+
+## Documentation Format
+
+All documentation files follow a consistent format:
+1. Component name and purpose
+2. Props/Inputs table with types, defaults, and descriptions
+3. TypeScript type definitions
+4. Usage examples covering common use cases
+5. Behavior notes explaining important details
+6. Related components and links
+
+## Quick Reference
+
+| Component | File | Primary Use Case |
+|-----------|------|------------------|
+| Button | `docs/Button.md` | User actions and interactions |
+| Typography | `docs/Typography.md` | Text content and headings |
+| Icon | `docs/Icon.md` | Visual icons and symbols |
+| MediaObject | `docs/MediaObject.md` | Media + content layouts |
+
+## Additional Resources
+
+- Component source code: `src/components/`
+- Storybook documentation: Available at the project's Storybook instance
+- Type definitions: `src/types/` and component-specific type exports
+- Storybook static build: `storybook-static/`
+- Component stories: `src/stories/`
+
+## Installation
+
+```bash
+npm install cleanplate
+```
+
+## Usage
+
+```jsx
+import { Button, Typography, Icon, MediaObject } from "cleanplate";
+```

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "cleanplate",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "CleanPlate - A Headless React UI Framework",
   "main": "dist/index.js",
   "module": "dist/index.es.js",
+  "types": "dist/index.d.ts",
   "scripts": {
     "storybook": "storybook dev -p 6001",
     "build-storybook": "storybook build",
-    "build-package": "rollup -c",
+    "build-package": "rollup -c && npm run build-types",
+    "build-types": "tsc --emitDeclarationOnly",
+    "type-check": "tsc --noEmit",
     "generate-llms-txt": "storybook-llms-extractor --config llms.config.js"
   },
   "repository": {
@@ -27,6 +30,7 @@
   "homepage": "https://cleanplate.sivadass.in",
   "devDependencies": {
     "@babel/preset-react": "^7.23.3",
+    "@babel/preset-typescript": "^7.28.5",
     "@floating-ui/react": "^0.27.16",
     "@fluentui/storybook-llms-extractor": "^0.0.2",
     "@rollup/plugin-babel": "^6.0.4",
@@ -40,6 +44,10 @@
     "@storybook/react": "^7.5.3",
     "@storybook/react-vite": "^7.5.3",
     "@storybook/testing-library": "^0.2.2",
+    "@types/node": "^25.0.9",
+    "@types/react": "^19.2.8",
+    "@types/react-dom": "^19.2.3",
+    "baseline-browser-mapping": "^2.9.16",
     "prop-types": "^15.8.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
@@ -47,7 +55,8 @@
     "rollup-plugin-peer-deps-external": "^2.2.4",
     "rollup-plugin-postcss": "^4.0.2",
     "sass": "^1.72.0",
-    "storybook": "^7.5.3"
+    "storybook": "^7.5.3",
+    "typescript": "^5.9.3"
   },
   "peerDependencies": {
     "react": ">=18",

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "checkJs": false,
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "sourceMap": true,
+    "strict": false,
+    "noImplicitAny": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "storybook-static", "**/*.stories.*", "**/*.test.*", "**/*.spec.*"]
+}