Automatic fetching and displaying of data through declarative data types.
This library is indended to facilitate displaying data on simple components by having a model of your data.
It can save you A lot of coding in you application!
With it, you can easily grab data from a "MetaHandler" from whatever sources, and use it anywhere with the same API (agnostic to how you fetch the data).
npm i --save-dev @tty-pt/typesHere, we don't use a MetaHandler, just some other features of types, to display a simple table:
import { Str, Table } from "@tty-pt/types"
const type = new Shape("Actor", {}, {
name: new Str("Name"),
});
export default function NameTable() {
return (<Table
type={type}
data={[{ name: "Joe Smith" }]}
columns={[ "name" ]}
options={{}}
details={[[ "name" ]]}
/>);
}import { Str, Shape, Enum, Bool } from "@tty-pt/types";
import { IconGood, IconBad, IconNeutral } from "example";
import { fetcher, indexer } from "lib/dependencies";
const STATE = {
good: 0,
bad: 1,
neutral: 2,
};
const STATE_MAP = {
0: { title: "good", icon: IconGood },
1: { title: "bad", icon: IconBad },
1: { title: "neutral", icon: IconNeutral },
};
const incomingType = new Shape("Actor", {}, {
name: new Str("Name"),
state: new Enum("State", {
default: STATE.good, // data will be set to this, even if it is not received
getter: (_, data) => data.deeper.state
}, STATE, STATE_MAP);
alive: new Bool("Alive", {
// a global meta handler will run these calls, but not a local one.
onChange: (value) => console.log("Alive changed", value),
}, STATE, STATE_MAP),
});
class ExampleMetaHandler extends MetaHandler {
constructor(type, options = {}) {
super(type, options.fetcher, options.indexer, options);
}
}
function createHandler(type, options = {}) {
return new MetaHandler(type, options.fetcher, options.indexer, options);
}
// most of the above could easily be in other files and be shared across views
// if you had a different outcoming type from the incoming type,
// you would provide an "adapter" to map the data to the options argument
const tableHandler = createHandler(incomingType, { fetcher, indexer });
const outgoingType = incomingType;
function App() {
const data = useMeta(tableHandler);
return (<Table
type={outgoingType}
data={data}
columns={["name", "state", "alive"]}
options={{}}
/>);
}For every type, the first argument of the constructor is the title of the data field. This text is shown in the details and table header. The second (optional) argument is "meta": It can be used to customize the behavior of the type. In this section we discuss the "meta" properties that can be used in all types.
This is a function with the following signature:
function getter(type, data, meta, parentKey) { /* ... */ }It is used to customize how the data is obtained.
This is a string but it is somewhat similar to "getter", it is used to automatically fetch from a property of "data".
When the data is undefined, return the value of this property.
This is a function with the following signature:
function onChange(value) { /* ... */ }It will be run if the MetaHandler has an option named "global", and if the data corresponding to the data field of the type has changed. This is useful to have global onChange logic outside of components.
This is the value of the declaration to be used when the value of the type is undefined.
This is the value of the tooltip to displayed on undefined values.
Instance of a function that does string internationalization.
These are some base types provided with this library. These types have a lot of functionalities associated with them. For example they can render their value using icons, in most cases. They each have slightly different ways of being displayed in different situations, and to be filtered through.
An integer number
const type = new Integer("Age"); // or new Integer("Age", { default: 0 })A String
const type = new Str("Name"); // or new Str("Name", { default: "Joe" })Same as Str but it is used for rendering components. This serves to provide generic functionality to many other types.
A percentual value between 0 and 100. This shows any of a number of icons, according to its value.
const type = new Percent("Battery", {}, [IconA, IconB, IconC]);An Enum or an integer value that corresponds to some properties.
const type = new Enum("Status", {}, declaration, map);Like Enum but for boolean values
const map = {
[true]: { title: "true", icon: TrueIcon },
[false]: { title: "false", icon: FalseIcon },
};
const type = new Bool("Status", {}, map);Like Bool but renders a checkbox instead of an icon
const type = new Checkbox("Status", {}, map);Like Bool but it has a notion of recursion. It has a map of sub-types.
const type = new Shape("Human", {}, map, {
name: new Str("Name"),
age: new Integer("Age"),
});Like Shape but it has a different notion of recursion. It has a map in which each key may correspond to a value of a certain type.
const type = new Dictionary("Names", {}, map, Str, []);Fourth argument is the SubType, and the fifth is the array of arguments provided to the SubType constructor.
This has a value of type Date.
const type = new DateTime("DateTime"); // or new DateTime("Time", { format: "time", measure: 0.001 });This type has the following custom meta properties:
This meta property is a numeric value. This value is to be multiplied by the received data in order to get the Date object.
This is used to customize the way that the DateTime string is presented. This can be "date", "time" or other values. If the value is "date", only the date is shown, if it is "time" only the time is shown. Otherwise the time is always shown, and the date is shown when it differs from current date.
This is of a Function type. It is rendered as a button that calls that function.
const type = new Fun("Callback");This is a class that helps fetch data based on type information.
const options = {}
const exampleHandler = new MetaHandler(type, fetcher, indexer, options);It receives four arguments in the constructor, the type, the fetcher, the indexer and the options object.
Fetcher is an instance of a class that must have three methods: getAll, subscribe and unsubscribe. The getAll method receives a callback with the received data as an argument. The subscribe method receives a callback with the received data as an argument. And it returns a subscription key. The unsubscribe method receives a subscription key.
Indexer is an instance of a class that must have two methods: subscribe and unsubscribe. The subscribe method receives a callback with the received data as an argument. And it returns a subscription key. The unsubscribe method receives a subscription key.
Now suppose you want to create a type based on Dictionary, but that has a preset map that it uses. So that we don't need to provide the map every time you want a field of that type. You can do something like this:
// file: src/types.js
import { extend, Dictionary as InnerDictionary } from "@tty-pt/types";
export class Dictionary extends InnerDictionary {
constructor(title, meta, SubType, subTypeArgs) {
super(title, meta, BOOL_STATUS_MAP, SubType, subTypeArgs);
}
}
Dictionary.extend = (SubType, subTypeArgs = [], options = {}) =>
extend(Dictionary, [SubType, subTypeArgs], options);Then you can use it like so:
// file: src/views/Test.js
import { Dictionary } from "../types";
const type = new Dictionary("Names", {}, Str, []);
/* ... */You can also do the following signature to easily extend one of these classes:
export const Status = Bool.extend(BOOL_STATUS_MAP);To simplify specifying the props of the components, we will use typescript as pseudo-code.
// I will explain the following line a bit later, if you don't mind.
const Filters = (string | { filters: Filters, className: string } | React.ElementType)[];
interface TooltipProps {
tooltip: string;
children: React.Node;
className: string;
}
interface GlobalFilterProps {
value: any;
dataKey: string; // TODO rename to typeKey
onChange: any => void; // TODO fix return type
}
// these are classNames
interface Cast {
invalid: string, // invalid field
line: string, // draw a line
rotate: string, // rotate 90 degrees
outline: string, // outline all round
TextCenter: string, // center text
FHCenter: string, // flex center
Table: {
root: string,
title: string,
table, // main table component
th: string,
td: string,
Toolbar: {
root: string,
content: string, // usually contains filters
},
},
Label: {
title: string,
},
Details: {
root: string,
column: string,
header: string, // the main line
container: string, // for recurse types
title: string, // left side of header
},
List: {
root: string,
Toolbar: string,
},
Tooltip: {
root: string,
content: string,
},
TooltipCircle: string,
Str: {
Filter: string,
},
DateTime: {
Filter: string,
},
Enum: {
Label: string,
Filter: {
root: string,
active: string, // active chip
inactive: string, // inactive chip
},
},
}
interface TableProps {
columns: string[]; /* here you can specify paths to things that will be displayed,
* for example robot.name. This is similar to what you can give
* as filters. You can also give strings like these to filters.
*/
filters: Filters; // Sorry, please wait a bit more for a full explanation.
data: object[]; // Simply the data that is received for example from a MetaHandler.
icons: { // mui icons or similar
DetailPanel: React.Component; // expand icon (FIXME)
};
details?: string[][]; // these can only be simple words for now (FIXME)
t?: string => string; // translate functionality
type: Shape;
title?: string;
name?: string; // used for identifying which inputs belong to this table, in case the table has inputs.
components?: {
Tooltip?: React.Component<TooltipProps>; // Custom Tooltip for detail headers
};
cast?: Cast;
renderValue?: Boolean; // do you wish to render icons for enums, etc?
titleFormat?: string => string; // you can change how titles are displayed here
detailsTable?: Boolean; // do you wish to try to show details as sub-tables?
global?: { // provide this to specify that you want some sort of global filtering
filter?: (type: BaseType, item: object, filters: object) => Boolean;
Component?: React.Component<GlobalFilterProps>;
};
}Well this is just to display a list of components. It has no special use other than filtering. The API may change.
interface ListItemProps {
index: Number;
data: object;
}
interface ListProps {
data: object[];
style: object;
type: Shape;
filters: Filters; // just a bit more...
onClick: object; // FIXME
Component: React.Component<ListItemProps>;
[key: string]?: any;
}Filters, as previously stated, has a format like the following:
const Filters = (string | { filters: Filters, className: string } | React.ElementType)[];So, it is an array. It can be an array of strings, Elements or that option in the middle. Aka:
const BoxFilters = { filters: Filters, className: string };If it is in this format, well it has a sort of recursive behavior in which you can specify the layout a bit better to account for a couple of situations.