{"id":20455889,"url":"https://github.com/nevoland/realue","last_synced_at":"2025-04-13T03:42:39.508Z","repository":{"id":28159552,"uuid":"116516473","full_name":"nevoland/realue","owner":"nevoland","description":"⚛️ Simple value management for React components.","archived":false,"fork":false,"pushed_at":"2025-01-28T14:05:45.000Z","size":3476,"stargazers_count":12,"open_issues_count":8,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-26T20:51:33.390Z","etag":null,"topics":["component","polymorphism","react","reuse","value"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nevoland.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-06T21:21:55.000Z","updated_at":"2025-01-09T10:16:25.000Z","dependencies_parsed_at":"2023-11-07T03:27:54.324Z","dependency_job_id":"2fc96f72-7d66-4288-9971-f0098b7fff4b","html_url":"https://github.com/nevoland/realue","commit_stats":{"total_commits":417,"total_committers":7,"mean_commits":59.57142857142857,"dds":0.0695443645083933,"last_synced_commit":"1471243278b2a94afc3c3ec9b0ffbfdb06796fbf"},"previous_names":["nevoland/realue"],"tags_count":260,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevoland%2Frealue","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevoland%2Frealue/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevoland%2Frealue/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nevoland%2Frealue/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nevoland","download_url":"https://codeload.github.com/nevoland/realue/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248217146,"owners_count":21066633,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["component","polymorphism","react","reuse","value"],"created_at":"2024-11-15T11:20:20.114Z","updated_at":"2025-04-13T03:42:39.491Z","avatar_url":"https://github.com/nevoland.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Realue\n\n⚛️ Simple value management for React components.\n\n### Features\n\n- Enforces reusable components based on the `{ name, error, value, onChange(value, name), onChangeError(error, name) }` properties, also called the \"NEVO\" pattern.\n- Provides helpers for effortlessly handling complex structured value types (arrays and objects, aka lists and maps) and their potential errors.\n- Considerably reduces boilerplate code by handling the application state directly in components, and shaping it through the component structure.\n- Brings efficient asynchronous handlers for sending data to persistence systems.\n\n## Installation\n\nInstall with the [Node Package Manager](https://www.npmjs.com/package/realue):\n\n```bash\nnpm install realue\n```\n\n## Usage\n\nEverything is exported from the main entry-point through an ES6 module.\n\n### Quick start\n\nUse `useObject` to automatically handle an object property, or `useArray` for handling array items. Note how all the values are handled gracefully, without having to write boilerplate code.\n\n```tsx\nimport { useArray, useObject, useRemove, useDebounce } from \"realue\";\nimport type { NevoProps, ValueRemover } from \"realue\";\n\ntype UserType = {\n  name?: string;\n  level?: number;\n};\n\nfunction User(props: NevoProps\u003cUserType\u003e \u0026 { onRemove?: ValueRemover }) {\n  const property = useObject(props);\n  const onRemove = useRemove(props);\n  return (\n    \u003c\u003e\n      \u003cInput label=\"Name\" {...property(\"name\")} /\u003e\n      \u003cInputNumber label=\"Level\" {...property(\"level\")} /\u003e\n      \u003cbutton onClick={onRemove}\u003eDelete user\u003c/button\u003e\n    \u003c/\u003e\n  );\n}\n\nfunction UserList(props: NevoProps\u003cUserType[]\u003e) {\n  const item = useArray(props);\n  return (\n    \u003c\u003e\n      {item.loop(User, { onRemove: item.remove })}\n      \u003cbutton onClick={item.add \u0026\u0026 (() =\u003e item.add({}))}\u003eAdd user\u003c/button\u003e\n    \u003c/\u003e\n  );\n}\n\nconst USER_LIST: UserType[] = [\n  { name: \"Alice\", level: 5 },\n  { name: \"Bob\", level: -2 },\n];\n\nconst USER_LIST_ERROR: ErrorReport\u003cUserType[]\u003e | undefined = undefined;\n\nexport default function App() {\n  const props = useSyncedProps({\n    name: \"userList\",\n    error: USER_LIST_ERROR,\n    value: USER_LIST,\n  });\n  return (\n    \u003c\u003e\n      \u003ch1\u003eUsers\u003c/h1\u003e\n      \u003cUserList {...props} /\u003e\n    \u003c/\u003e\n  );\n}\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eLibrary components used in the example\u003c/summary\u003e\n\n```tsx\nfunction extractInputValue\u003cT extends string | undefined\u003e({\n  value,\n}: HTMLInputElement) {\n  return (value === \"\" ? undefined : value) as T;\n}\n\nfunction Input(\n  props: NevoProps\u003cstring | undefined\u003e \u0026 { label: string; delay?: number },\n) {\n  const { value = \"\", name, onChange } = useDebounce(props, delay);\n  const onInput = useInput(props, extractInputValue);\n  return (\n    \u003cdiv class=\"flex flex-col space-y-1\"\u003e\n      \u003clabel\u003e{label}\u003c/label\u003e\n      {error \u0026\u0026 \u003cp class=\"text-red-500 dark:text-red-300\"\u003e{error.join(\" \")}\u003c/p\u003e}\n      \u003cinput\n        autoComplete=\"new-password\"\n        disabled={!onChange}\n        name={name}\n        onInput={onChange ? onInput : undefined}\n        placeholder={placeholder}\n        value={value}\n      /\u003e\n    \u003c/div\u003e\n  );\n}\n\nfunction extractInputNumberValue({ value }: HTMLInputElement) {\n  const parsedValue = parseFloat(value);\n  return isNaN(parsedValue) ? undefined : parsedValue;\n}\n\nexport const InputNumber = memo(function InputNumber(props: InputNumberProps) {\n  const {\n    value: currentValue,\n    name,\n    onChange,\n    label,\n    placeholder,\n    onValidate,\n    error,\n    onChangeError,\n  } = props;\n  const value =\n    currentValue === undefined\n      ? undefined\n      : isNaN(currentValue)\n      ? 0\n      : currentValue;\n  const onInput = useInput(props, extractInputNumberValue);\n  return (\n    \u003cdiv class=\"flex flex-col space-y-1\"\u003e\n      \u003clabel\u003e{label}\u003c/label\u003e\n      {error \u0026\u0026 \u003cp class=\"text-red-500 dark:text-red-300\"\u003e{error.join(\" \")}\u003c/p\u003e}\n      \u003cinput\n        autoComplete=\"off\"\n        disabled={!onChange}\n        name={name}\n        onInput={onChange ? onInput : undefined}\n        placeholder={placeholder}\n        type=\"number\"\n        value={value === undefined ? \"\" : value}\n      /\u003e\n    \u003c/div\u003e\n  );\n});\n```\n\n\u003c/details\u003e\n\n### Error handling\n\nChanging the `USER_LIST_ERROR` in the example above to the following value, will automatically add a an error message for Bob's level value. These errors can be either passed down to components through the `error` prop, but also communicated back up through the `onChangeError` property.\n\n```tsx\nconst USER_LIST_ERROR: ErrorReport\u003cUserType[]\u003e | undefined = {\n  1: { level: [\"The level must be a positive number.\"] },\n};\n```\n\nThe `error` value follows a [simple structure](doc/README.md#errorreport) to map error messages to specific values:\n\n- An error report for a [primitive value](doc/README.md#errorreportvalue) (e.g., a `boolean`, `number`, or `string` value) consists of a list of one or several strings (e.g., `[\"This is not an email address.\"]`).\n- Error reports for [objects](doc/README.md#errorreportobject) consist of a mapping of property names to error reports (e.g. `{ name: [\"The name is missing.\"] }`). In case of an error that pertains to the entire value, it can either be stored at the empty string key in case that there are also errors for specific properties (e.g., `{ \"\": [\"Either the username or the email address must be set.\"], \"level\": [\"The level must be positive.\"] }`), or directly as a list of strings: `[\"Either the username or the email address must be set.\"]`.\n- Error reports for [arrays](doc/README.md#errorreportarray) are similar to those for objects, except that they map item indices to error reports (e.g., `{ 1: { \"name\": [\"The name is required and cannot be empty.\"] } }`). As well as in error reports for objects, an error report for the entire array could be set at the empty string key if there are errors for the array items, or directly as a list of strings.\n\n### Property name conventions\n\nComponents handle a value and render it. That value is received through the `value` property.\n\nIt also gets an optional error report that can be provided through the `error` property.\n\nAny callback name starts with the `\"on\"` prefix: `onChange` is used to report a `value` change, `onChangeError` serves to update the `error`.\n\n## Documentation\n\nCheckout the [API documentation](doc/README.md).\n\n## Demo\n\nA demo application can be run in the browser with:\n\n```bash\nnpm run build\nnpm start\nopen http://localhost:1234\n```\n\nYou can then inspect and edit the code in the `demo/` folder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnevoland%2Frealue","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnevoland%2Frealue","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnevoland%2Frealue/lists"}