npm.io
1.0.10 • Published 13h ago

protonus

Licence
MIT
Version
1.0.10
Deps
4
Size
867 kB
Vulns
0
Weekly
0

protonus

React UI library for building CRUD/reference interfaces over OData (and custom data providers).

  • Metadata-driven tables, cards, editors, fields, filters and sorters
  • OData V4 provider with $select / $expand / $filter / $orderby support
  • TypeScript source and generated .d.ts declarations
  • React 18/19, Ant Design 5/6, React Router 6/7

Install

npm i protonus antd @ant-design/icons antd-table-ext dayjs react react-dom react-router-dom

The major versions of antd and @ant-design/icons must match:

Stack antd @ant-design/icons React react-router-dom
Latest ^6.7.0 ^6.3.0 ^19.0.0 ^7.0.0
Legacy ^5.29.0 ^5.6.0 ^18.2.0 ^6.28.0

Quick start

import { useMetadata, useList, Table } from 'protonus';

const userMetadata = {
    entity: 'Users',
    key: 'id',
    properties: [
        { dataIndex: 'id', type: 'number' },
        { dataIndex: 'name', type: 'string', required: true },
        { dataIndex: 'createdAt', type: 'datetime' }
    ]
};

export function UsersPage() {
    const metadata = useMetadata(userMetadata);
    const list = useList({ metadata });

    return <Table metadata={metadata} list={list} />;
}

The default data provider reads globalSettings.dataProvider.odataPath. Set it once during application bootstrap:

import protonus from 'protonus';

protonus.dataProvider.odataPath = 'https://example.com/odata';

Settings

globalSettings remains the backward-compatible default. createSettings and SettingsProvider scope the data provider, pageSize, hierarchical loading, metadata types/defaults and the state hooks:

import { createSettings, SettingsProvider } from 'protonus';

const settings = createSettings({
    pageSize: 50,
    dataProvider: myProvider
});

<SettingsProvider settings={settings}>
    <App />
</SettingsProvider>

useList, useEntity, useMetadata and the metadata layer read settings from the provider and fall back to globalSettings.

UI display settings (locale, date formats, onApply, editInCard, field/appearance defaults) are still read from globalSettings. Configure them globally if you need a different locale or editing behavior.

URL state limitation

Row selection is stored in the URL as a comma-separated list (rowChSel). String keys containing a literal comma are not supported by this storage format.

Metadata and types

Property types: string, text, number, boolean, enum, date, datetime, duration, entity, file, dictionary, color, code, expression, chain, function.

Data-provider hooks can be configured per property:

{
    dataIndex: 'customer/name',
    type: 'string',
    filterSerialize: (value) => JSON.stringify(value),
    filterDeserialize: (value) => JSON.parse(value)
}

Custom data providers

Pass a provider to useList / useEntity, or register it in settings:

const list = useList({ metadata, dataProvider: myProvider });
const entity = useEntity({ metadata, id, dataProvider: myProvider });

A provider implements the methods used by the hooks: getList, getEntity, changeData, deleteData, and optionally getParents.

AGG Grid

The AGG Grid integration is an optional example, not part of the published package. See src/examples/aggrid.

SSR and styles

protonus is a client-side library. Hooks and components use window, document, localStorage and browser history, so server-side rendering is not officially supported. If SSR is required, render the library only on the client after hydration.

Styles are imported by components and injected at runtime via vite-plugin-css-injected-by-js; the package does not ship a standalone CSS file. Importing protonus on the client is enough to load its styles.

Development

npm test            # unit/integration tests
npm run typecheck   # TypeScript
npm run lint        # ESLint
npm run build       # ESM build + declarations

License

MIT

Keywords