react-markdown-table-ts 0.6.4 → 1.1.1

package/README.md

@@ -2,63 +2,102 @@
 
 [![NPM Version](https://img.shields.io/npm/v/react-markdown-table-ts.svg)](https://www.npmjs.com/package/react-markdown-table-ts)
 [![codecov](https://codecov.io/gh/keithwalsh/react-markdown-table-ts/branch/main/graph/badge.svg)](https://codecov.io/gh/keithwalsh/react-markdown-table-ts)
-![Build](https://github.com/keithwalsh/react-markdown-table-ts/actions/workflows/release.yaml/badge.svg)
+![Build](https://github.com/keithwalsh/react-markdown-table-ts/actions/workflows/build.yml/badge.svg)
 [![Code Climate](https://codeclimate.com/github/keithwalsh/react-markdown-table-ts/badges/gpa.svg)](https://codeclimate.com/github/keithwalsh/react-markdown-table-ts)
-
-A React component that converts structured data into Markdown table syntax and displays it within a `<pre>` tag.
-
-## ✨ Features
-
-- **Type Safety:** Built with TypeScript to provide strong type guarantees.
-- **Easy Integration:** Simple API for converting data arrays into Markdown table strings.
-- **Customizable Alignments:** Specify column alignments (left, center, right, or none) with ease.
-- **Compact Mode:** Option to generate compact tables with minimal padding.
-- **Tab-Separated Columns:** Option to add tabs between columns.
-- **Newline Handling: Option** to replace newlines in cells with HTML line breaks.
-- **Raw Markdown Access:** Retrieve the generated Markdown string for further processing or usage.
-- **Header Options:** Choose whether to include a header row or use default alphabetical headers.
-- **Flexible Styling:** Apply custom CSS classes for styling the rendered Markdown.
-
-## 📦 Installation
-
-Install the package via npm:
-
+[![GitHub branch status](https://img.shields.io/github/checks-status/keithwalsh/react-markdown-table-ts/HEAD)](https://github.com/keithwalsh/react-markdown-table-ts/commits/HEAD/)
+
+| ![Light Theme Example](public/light.png) | ![Dark Theme Example](public/dark.png)  |
+|------------------------------------------|-----------------------------------------|
+| `'light'` theme                          | `'dark'` theme                          |
+
+## Overview 
+This library provides a React component for generating and displaying formatted Markdown tables with syntax highlighting. The core component is `MarkdownTable` which converts 2D array data into properly formatted Markdown table syntax.
+
+## API
+```typescript
+interface MarkdownTableProps {
+    inputData?: string[][] | null;
+    columnAlignments?: readonly Alignment[];
+    isCompact?: boolean;
+    hasPadding?: boolean;
+    hasTabs?: boolean;
+    hasHeader?: boolean;
+    convertLineBreaks?: boolean;
+    theme?: 'light' | 'dark';
+    className?: string;
+    preStyle?: React.CSSProperties;
+    onGenerate?: (markdownTableString: string) => void;
+}
 ```
-
-npm install react-markdown-table-ts
-
+| Prop                 | Type                                    | Default     | Description                                                                        |
+|----------------------|-----------------------------------------|-------------|------------------------------------------------------------------------------------|
+| `inputData`          | `string[][] \| null`                    | `null`      | The outer array represents rows. The inner array represent cells within each row. |
+| `columnAlignments`   | `readonly Alignment[]`                  | `[]`	       | Acceptable values are 'left', 'center', 'right', or 'none'.                        |
+| `isCompact`          | `boolean`                               | `false`     | Disables column width alignment to provide a more compact markdown table string.   |
+| `hasPadding`         | `boolean`                               | `true`      | One space added before and after the content in each cell.                         |
+| `hasTabs`            | `boolean`                               | `false`     | Adds a tab character after each \| and before the content.                         |
+| `hasHeader`          | `boolean`                               | `true`      | Indicates whether the first row of `data` is a header.                             |
+| `convertLineBreaks`  | `boolean`                               | `false`     | Replace newlines with <br> tags in table cells.                                    |
+| `theme`              | `'light' \| 'dark'`                     | `light`     | Controls the color scheme of the \<pre\> element display.                            |
+| `className`          | `string`                                | `undefined` | Class will be applied to the \<pre\> element display.                                |
+| `preStyle`           | `React.CSSProperties`                   | `undefined` | Allows direct styling of the display with CSS properties.                          |
+| `onGenerate`         | `(markdownTableString: string) => void` | `undefined` | Callback to receive the generated Markdown table string.                           |
+## Usage Patterns
+
+1. **Basic Table Generation**:
+```typescript
+<MarkdownTable
+    inputData={[
+        ["Header 1", "Header 2"],
+        ["Row 1 Col 1", "Row 1 Col 2"]
+    ]}
+/>
+```
+2. **Column Alignment**:
+```typescript
+<MarkdownTable
+    inputData={data}
+    columnAlignments={['left', 'center', 'right']}
+/>
+```
+3. **Auto-Generated Headers**:
+```typescript
+<MarkdownTable
+    inputData={data}
+    hasHeader={false} // Will generate A, B, C... headers
+/>
 ```
 
-## 🔧 API
+## Behaviors
 
-### MarkdownTable Props
+1. **Input Validation**:
+- Input must be non-null 2D string array
+- All rows should contain string values
+- Empty arrays are not allowed
+- Column alignments must be valid ('left', 'center', 'right', 'none')
 
-|         Prop         |                     Type                      |   Default   |                 Description                 |
-| :------------------: | :-------------------------------------------: | :---------: | :-----------------------------------------: |
-|        `data`        |                 `string[][]`                  |   `null`    |   The table data as a 2D array of strings   |
-|  `columnAlignments`  | `('left' \| 'center' \| 'right' \| 'none')[]` |    `[]`     |          Alignment for each column          |
-|     `isCompact`      |                   `boolean`                   |   `false`   |          Use minimal column widths          |
-|     `className`      |                   `string`                    | `undefined` |        CSS class for the `<pre>` tag        |
-|      `hasTabs`       |                   `boolean`                   |   `false`   |       Add tabs between table columns        |
-| `canReplaceNewlines` |                   `boolean`                   |   `false`   | Replace newlines in cells with `<br>` tags  |
-|   `onTableCreate`    |      `(markdownString: string) => void`       | `undefined` |   Callback to receive the Markdown string   |
-|     `hasHeader`      |                   `boolean`                   |   `true`    | Whether the first row of `data` is a header |
+2. **Column Width Handling**:
+- Default: Adjusts columns to fit content
+- `isCompact={true}`: Minimizes column widths
+- Maintains minimum width of 3 characters for alignment indicators
 
-## 🚀 Usage
+3. **Error Handling**:
+- Returns error message string if validation fails
+- Wraps errors in `MarkdownTableError` class
+- Preserves stack traces for debugging
 
-```jsx
-import React from 'react';
-import {MarkdownTable} from 'markdown-table-component';
+4. **Styling**:
+- Uses Prism.js for syntax highlighting
+- Supports light/dark themes
+- Custom styles via `className` and `preStyle` props
 
-const App = () => {
-  const data = [
-    ['Header 1', 'Header 2', 'Header 3'],
-    ['Row 1, Col 1', 'Row 1, Col 2', 'Row 1, Col 3'],
-    ['Row 2, Col 1', 'Row 2, Col 2', 'Row 2, Col 3'],
-  ];
+## Common Transformations
 
-  return <MarkdownTable data={data} />;
-};
+1. **Data Formatting**:
+- Newlines can be converted to `<br>` tags with `canReplaceNewlines`
+- Padding can be controlled with `hasPadding`
+- Tab spacing available with `hasTabs`
 
-export default App;
-```
+2. **Header Generation**:
+- Auto-generates A, B, C... headers when `hasHeader={false}`
+- Supports custom headers via first row when `hasHeader={true}`

package/dist/MarkdownTable.stories.d.ts

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview Storybook stories for the MarkdownTable component, demonstrating
+ * various configurations and use cases for markdown table generation and display.
+ */
+/// <reference types="react" />
+import type { StoryObj } from '@storybook/react';
+import { MarkdownTable } from './index';
+declare const meta: {
+    title: string;
+    component: import("react").FC<import("./types").MarkdownTableProps>;
+    parameters: {
+        layout: string;
+    };
+    tags: string[];
+    args: {
+        inputData: null;
+        columnAlignments: never[];
+        isCompact: false;
+        hasPadding: true;
+        hasTabs: false;
+        hasHeader: true;
+        convertLineBreaks: false;
+        theme: "light";
+    };
+    argTypes: {
+        inputData: {
+            control: {
+                type: "object";
+            };
+            description: string;
+            table: {
+                category: string;
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        columnAlignments: {
+            control: {
+                type: "object";
+            };
+            description: string;
+            table: {
+                category: string;
+                type: {
+                    summary: string;
+                    detail: string;
+                };
+            };
+        };
+        isCompact: {
+            control: "boolean";
+            description: string;
+            table: {
+                category: string;
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        hasPadding: {
+            control: "boolean";
+            description: string;
+            table: {
+                category: string;
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        hasTabs: {
+            control: "boolean";
+            description: string;
+            table: {
+                category: string;
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        hasHeader: {
+            control: "boolean";
+            description: string;
+            table: {
+                category: string;
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        convertLineBreaks: {
+            control: "boolean";
+            description: string;
+            table: {
+                category: string;
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        theme: {
+            options: string[];
+            control: {
+                type: "select";
+            };
+            description: string;
+            table: {
+                category: string;
+                type: {
+                    summary: string;
+                };
+                defaultValue: {
+                    summary: string;
+                };
+            };
+        };
+        className: {
+            control: "text";
+            description: string;
+            table: {
+                category: string;
+                type: {
+                    summary: string;
+                };
+            };
+        };
+        preStyle: {
+            control: {
+                type: "object";
+            };
+            description: string;
+            table: {
+                category: string;
+                type: {
+                    summary: string;
+                };
+            };
+        };
+    };
+};
+export default meta;
+type Story = StoryObj<typeof MarkdownTable>;
+export declare const Default: Story;