@native-html/heuristic-table-plugin
    TypeScript icon, indicating that this package has built-in type declarations

    0.7.0 • Public • Published

    ⚠️ This plugin is in active development and its API might change without notice. As long as it is unstable, it will be released with 0.X version scheme, as per the semver standard.

    @native-html/heuristic-table-plugin

    npm semver codecov CI DL/month Discord

    🔠 A 100% native component using heuristics to render tables in react-native-render-html.


    npm add --save @native-html/heuristic-table-plugin
    yarn add @native-html/heuristic-table-plugin

    Compat Table

    react-native-render-html @native-html/heuristic-table-plugin
    < 6.0.0 -
    ≥ 6.0.0 6.x (documentation)

    Minimal working example

    import React from 'react';
    import { ScrollView } from 'react-native';
    import HTML from 'react-native-render-html';
    import tableRenderers from '@native-html/heuristic-table-plugin';
    
    const html = `
    <table>
      <tr>
        <th>Entry Header 1</th>
        <th>Entry Header 2</th>
      </tr>
      <tr>
        <td>Entry First Line 1</td>
        <td>Entry First Line 2</td>
      </tr>
    </table>
    `;
    
    const htmlProps = {
      WebView,
      renderers: {
        ...tableRenderers
      },
      renderersProps: {
        table: {
          // Put the table config here
        }
      }
    };
    
    export const Example = () => (
      <ScrollView>
        <HTML source={{ html }} {...htmlProps} />
      </ScrollView>
    );

    Configuration

    To change the layout of cells and other options, you can pass a config object to the renderersProps.table prop of RenderHTML component.

    See the documentation for this object here: HeuristicTablePluginConfig

    Custom Renderers

    Customizing Root renderer

    You can customize the renderer logic thanks to useHtmlTableProps hook and HTMLTable exports:

    import React from 'react';
    import tableRenderers, {useHtmlTableProps, HTMLTable} from '@native-html/heuristic-table-plugin';
    
    function TableRenderer(props) {
      const tableProps = useHtmlTableProps(props, /* config */);
      // Do customize the props here; wrap with your own container...
      return <HTMLTable {..tableProps} />;
    };
    
    const renderers = {
      ...tableRenderers,
      table: TableRenderer
    }
    
    // use "renderers" prop in your RenderHTML instance

    Customizing Th and Td renderers

    You can customize cell rendering via useHtmlTableCellProps, thModel and tdModel exports. This renderer will receive a special propsFromParent of type TableCellPropsFromParent. You can take advantage of this information to customize depending on the position of the cell in the grid system coordinate, as shown below:

    import React from 'react';
    import {
      TableRenderer,
      ThRenderer,
      useHtmlTableCellProps,
      tdModel
    } from '@native-html/heuristic-table-plugin';
    
    function TdRenderer(props) {
      const cellProps = useHtmlTableCellProps(props);
      // The cell parent prop contains information about this cell,
      // especially its position (x, y) and lengths (lenX, lenY).
      // In this example, we customize the background depending on the
      // y coordinate (row index).
      const { cell } = cellProps.propsFromParent;
      const style = [
        cellProps.style,
        backgroundColor: cell.x % 2 === 0 ? 'lightgray' : 'white'
      ]
      return React.createElement(cellProps.TDefaultRenderer, { ...cellProps, style });
    }
    
    const renderers = {
      table: TableRenderer,
      td: TdRenderer,
      th: ThRenderer
    }
    
    // use "renderers" prop in your RenderHTML instance

    The heuristic layout algorithm

    Finding the cell sizes which result in the table of the least height given a fixed width is a NP complete problem.

    To resolve this problem, this library uses a dumb and cheap algorithm, which won't find the best solution but instead a visually acceptable layout.

    1. Cell constraints extraction

    In the first step, each cell of the table is parsed to extract two metrics: minWidth and contentDensity. minWidth is an estimation of the width taken by the longest word in the cell, or the explicit width or min-width of any block in the cell, or the greatest of the two. contentDensity is the width taken by all the text displayed in one line.

    2. Column constraints reduction

    In the second step, cell constraints are reduced per column. Three metrics come out:

    • minWidth, the maximum of each cell minWidth;
    • contentDensity, the sum of each cell contentDensity;
    • spread, the maximum of each cell contentDensity.

    3. Column widths calculation

    Let minTableWidth be the sum of all column minWidth. If minTableWidth > contentWidth, assign to each column a width corresponding to its minWidth constraint.

    Otherwise, let spaceToAllocate = contentWidth - minTableWidth. Allocate to each column a width equal to its minWidth constraint + spaceToAllocate * gamma, with gamma = (normalContentDensity) / sum(normalContentDensities). The normalContentDensity is contentDensity - min(contentDensities).

    Finally, clamp the assign width to the spread constraint for this column, unless forceStretch parameter is set to true.

    Install

    npm i @native-html/heuristic-table-plugin

    DownloadsWeekly Downloads

    65

    Version

    0.7.0

    License

    MIT

    Unpacked Size

    251 kB

    Total Files

    152

    Last publish

    Collaborators

    • jsamr