diff --git a/docs/development.md b/docs/development.md index 21f7e67..4d9235c 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,25 +1,27 @@ -Sooner or later, you will face with situation when you want/need to make some -changes in the library. Then the most important tool for you it's the -[`npm link`](https://docs.npmjs.com/cli/link). +At some point, you'll likely need to modify the library. When that happens, your +best friend will be [`npm link`](https://docs.npmjs.com/cli/link). -Please, notice that it will not work if you link the library just from the root -of the repo. It happens due to the location of sources `./src`. You need to pack -the library first, `make pack` and then link it from the `./dist` directory. +**Important Note:** Simply linking from the repo root won't work because the +source files are in `./src`. Instead, you'll need to: -Yeah, it's not such a comfortable solution for development. But it can be fixed -by writing a small script similar to making a pack but by linking every file and -directory from `./src` to the same directory and linking then from it. Notice -that you need to link a `package.json` and a `package-lock.json` as well. +1. First package the library using `make pack` +2. Then link it from the `./dist` directory -So step by step: +While this isn't the most developer-friendly workflow, you can improve it by +creating a script that: + +- Symlinks all files/directories from `./src` to another location +- Also links `package.json` and `package-lock.json` + +## Quick Start Guide ```bash -make pack; -cd dist; -npm link; +# Package and link the library +make pack +cd dist +npm link -cd $project_dir/js # Navigate to JS directory of the project where you want to link the library +# Link to your project +cd /path/to/your/project/js # Navigate to your project's JS directory npm link foris ``` - -And that's it ;) diff --git a/docs/introduction.md b/docs/introduction.md index d853b4c..428afbd 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -1,35 +1,37 @@ -Welcome! This is the official documentation for Foris JS. +Welcome to the official Foris JS documentation! -## What Foris JS is +## About Foris JS -Foris JS library is a set of components and utils for reForis application and -plugins. +Foris JS is a library containing reusable components and utilities designed +specifically for the reForis application and its plugins. -Please notice that all of these components or utils are used in reForis and -plugins. If you want to study them by example, I recommend you to full-text -search those repositories. +**Note:** All components and utilities in this library are actively used in +reForis and its plugins. To see practical examples of how they're implemented, +we recommend searching through those repositories. -# Installation +## Getting Started -## Prerequisites +### Prerequisites -Please make sure that [Node.js](https://nodejs.org/en/) is installed on your -system. +Before installing, ensure you have [Node.js](https://nodejs.org/en/) installed +on your system. -The current Long Term Support (LTS) release is an ideal starting point, see -[here](https://github.com/nodejs/Release#release-schedule). +We recommend using the current Long Term Support (LTS) version for optimal +compatibility. Check the +[release schedule](https://github.com/nodejs/Release#release-schedule) for +details. -## Installation +### Installation -To install the latest release: +Install the latest version with: -```plain +```bash npm install foris ``` -To install a specific version: +Or install a specific version by running: -```plain +```bash npm install foris@version ``` diff --git a/package-lock.json b/package-lock.json index 3dd99f6..aef5766 100644 --- a/package-lock.json +++ b/package-lock.json @@ -450,25 +450,27 @@ } }, "node_modules/@babel/helpers": { - "version": "7.26.9", - "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.26.9.tgz", - "integrity": "sha512-Mz/4+y8udxBKdmzt/UjPACs4G3j5SshJJEFFKxlCGPydG4JAHXxjWjAwjd09tf6oINvl1VfMJo+nB7H2YKQ0dA==", + "version": "7.27.0", + "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.27.0.tgz", + "integrity": "sha512-U5eyP/CTFPuNE3qk+WZMxFkp/4zUzdceQlfzf7DdGdhp+Fezd7HD+i8Y24ZuTMKX3wQBld449jijbGq6OdGNQg==", "dev": true, + "license": "MIT", "dependencies": { - "@babel/template": "^7.26.9", - "@babel/types": "^7.26.9" + "@babel/template": "^7.27.0", + "@babel/types": "^7.27.0" }, "engines": { "node": ">=6.9.0" } }, "node_modules/@babel/parser": { - "version": "7.26.9", - "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.26.9.tgz", - "integrity": "sha512-81NWa1njQblgZbQHxWHpxxCzNsa3ZwvFqpUg7P+NNUU6f3UU2jBEg4OlF/J6rl8+PQGh1q6/zWScd001YwcA5A==", + "version": "7.27.0", + "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.27.0.tgz", + "integrity": "sha512-iaepho73/2Pz7w2eMS0Q5f83+0RKI7i4xmiYeBmDzfRVbQtTOG7Ts0S4HzJVsTMGI9keU8rNfuZr8DKfSt7Yyg==", "dev": true, + "license": "MIT", "dependencies": { - "@babel/types": "^7.26.9" + "@babel/types": "^7.27.0" }, "bin": { "parser": "bin/babel-parser.js" @@ -1794,10 +1796,11 @@ } }, "node_modules/@babel/runtime": { - "version": "7.24.7", - "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.24.7.tgz", - "integrity": "sha512-UwgBRMjJP+xv857DCngvqXI3Iq6J4v0wXmwc6sapg+zyhbwmQX67LUEFrkK5tbyJ30jGuG3ZvWpBiB9LCy1kWw==", + "version": "7.27.0", + "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.27.0.tgz", + "integrity": "sha512-VtPOkrdPHZsKc/clNqyi9WUA8TINkZ4cGk63UUE3u4pmB2k+ZMQRDuIOagv8UVd6j7k0T3+RRIb7beKTebNbcw==", "dev": true, + "license": "MIT", "dependencies": { "regenerator-runtime": "^0.14.0" }, @@ -1806,14 +1809,15 @@ } }, "node_modules/@babel/template": { - "version": "7.26.9", - "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.26.9.tgz", - "integrity": "sha512-qyRplbeIpNZhmzOysF/wFMuP9sctmh2cFzRAZOn1YapxBsE1i9bJIY586R/WBLfLcmcBlM8ROBiQURnnNy+zfA==", + "version": "7.27.0", + "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.27.0.tgz", + "integrity": "sha512-2ncevenBqXI6qRMukPlXwHKHchC7RyMuu4xv5JBXRfOGVcTy1mXCD12qrp7Jsoxll1EV3+9sE4GugBVRjT2jFA==", "dev": true, + "license": "MIT", "dependencies": { "@babel/code-frame": "^7.26.2", - "@babel/parser": "^7.26.9", - "@babel/types": "^7.26.9" + "@babel/parser": "^7.27.0", + "@babel/types": "^7.27.0" }, "engines": { "node": ">=6.9.0" @@ -1838,10 +1842,11 @@ } }, "node_modules/@babel/types": { - "version": "7.26.9", - "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.26.9.tgz", - "integrity": "sha512-Y3IR1cRnOxOCDvMmNiym7XpXQ93iGDDPHx+Zj+NM+rg0fBaShfQLkg+hKPaZCEvg5N/LeCo4+Rj/i3FuJsIQaw==", + "version": "7.27.0", + "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.27.0.tgz", + "integrity": "sha512-H45s8fVLYjbhFH62dIJ3WtmJ6RSPt/3DRO0ZcT2SUiYiQyz3BLVb9ADEnLl91m74aQPS3AzzeajZHYOalWe3bg==", "dev": true, + "license": "MIT", "dependencies": { "@babel/helper-string-parser": "^7.25.9", "@babel/helper-validator-identifier": "^7.25.9" @@ -19002,22 +19007,22 @@ } }, "@babel/helpers": { - "version": "7.26.9", - "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.26.9.tgz", - "integrity": "sha512-Mz/4+y8udxBKdmzt/UjPACs4G3j5SshJJEFFKxlCGPydG4JAHXxjWjAwjd09tf6oINvl1VfMJo+nB7H2YKQ0dA==", + "version": "7.27.0", + "resolved": "https://registry.npmjs.org/@babel/helpers/-/helpers-7.27.0.tgz", + "integrity": "sha512-U5eyP/CTFPuNE3qk+WZMxFkp/4zUzdceQlfzf7DdGdhp+Fezd7HD+i8Y24ZuTMKX3wQBld449jijbGq6OdGNQg==", "dev": true, "requires": { - "@babel/template": "^7.26.9", - "@babel/types": "^7.26.9" + "@babel/template": "^7.27.0", + "@babel/types": "^7.27.0" } }, "@babel/parser": { - "version": "7.26.9", - "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.26.9.tgz", - "integrity": "sha512-81NWa1njQblgZbQHxWHpxxCzNsa3ZwvFqpUg7P+NNUU6f3UU2jBEg4OlF/J6rl8+PQGh1q6/zWScd001YwcA5A==", + "version": "7.27.0", + "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.27.0.tgz", + "integrity": "sha512-iaepho73/2Pz7w2eMS0Q5f83+0RKI7i4xmiYeBmDzfRVbQtTOG7Ts0S4HzJVsTMGI9keU8rNfuZr8DKfSt7Yyg==", "dev": true, "requires": { - "@babel/types": "^7.26.9" + "@babel/types": "^7.27.0" } }, "@babel/plugin-bugfix-firefox-class-in-computed-class-key": { @@ -19887,23 +19892,23 @@ } }, "@babel/runtime": { - "version": "7.24.7", - "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.24.7.tgz", - "integrity": "sha512-UwgBRMjJP+xv857DCngvqXI3Iq6J4v0wXmwc6sapg+zyhbwmQX67LUEFrkK5tbyJ30jGuG3ZvWpBiB9LCy1kWw==", + "version": "7.27.0", + "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.27.0.tgz", + "integrity": "sha512-VtPOkrdPHZsKc/clNqyi9WUA8TINkZ4cGk63UUE3u4pmB2k+ZMQRDuIOagv8UVd6j7k0T3+RRIb7beKTebNbcw==", "dev": true, "requires": { "regenerator-runtime": "^0.14.0" } }, "@babel/template": { - "version": "7.26.9", - "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.26.9.tgz", - "integrity": "sha512-qyRplbeIpNZhmzOysF/wFMuP9sctmh2cFzRAZOn1YapxBsE1i9bJIY586R/WBLfLcmcBlM8ROBiQURnnNy+zfA==", + "version": "7.27.0", + "resolved": "https://registry.npmjs.org/@babel/template/-/template-7.27.0.tgz", + "integrity": "sha512-2ncevenBqXI6qRMukPlXwHKHchC7RyMuu4xv5JBXRfOGVcTy1mXCD12qrp7Jsoxll1EV3+9sE4GugBVRjT2jFA==", "dev": true, "requires": { "@babel/code-frame": "^7.26.2", - "@babel/parser": "^7.26.9", - "@babel/types": "^7.26.9" + "@babel/parser": "^7.27.0", + "@babel/types": "^7.27.0" } }, "@babel/traverse": { @@ -19922,9 +19927,9 @@ } }, "@babel/types": { - "version": "7.26.9", - "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.26.9.tgz", - "integrity": "sha512-Y3IR1cRnOxOCDvMmNiym7XpXQ93iGDDPHx+Zj+NM+rg0fBaShfQLkg+hKPaZCEvg5N/LeCo4+Rj/i3FuJsIQaw==", + "version": "7.27.0", + "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.27.0.tgz", + "integrity": "sha512-H45s8fVLYjbhFH62dIJ3WtmJ6RSPt/3DRO0ZcT2SUiYiQyz3BLVb9ADEnLl91m74aQPS3AzzeajZHYOalWe3bg==", "dev": true, "requires": { "@babel/helper-string-parser": "^7.25.9", diff --git a/src/bootstrap/Checkbox.md b/src/bootstrap/Checkbox.md index ccf1c43..49e82f0 100644 --- a/src/bootstrap/Checkbox.md +++ b/src/bootstrap/Checkbox.md @@ -4,7 +4,7 @@ using in foris forms. All additional `props` are passed to the `` HTML component. -```js +```jsx import { useState } from "react"; const [value, setValue] = useState(false); diff --git a/src/bootstrap/CopyInput.md b/src/bootstrap/CopyInput.md index dcd6b4c..b778664 100644 --- a/src/bootstrap/CopyInput.md +++ b/src/bootstrap/CopyInput.md @@ -4,7 +4,7 @@ be used with `readOnly` and `disabled` parameters, please see an example. All additional `props` are passed to the `` HTML component. -```js +```jsx import React, { useState } from "react"; const [value, setValue] = useState("Text to appear in clipboard."); diff --git a/src/bootstrap/DataTimeInput.md b/src/bootstrap/DataTimeInput.md index 4dfc33f..fb4af69 100644 --- a/src/bootstrap/DataTimeInput.md +++ b/src/bootstrap/DataTimeInput.md @@ -4,7 +4,7 @@ Adopted from `react-datetime/DateTime` datatime picker component. It uses It requires `ForisTranslations.locale` to be defined in order to use right locale. -```js +```jsx ForisTranslations = { locale: "en" }; import { useState, useEffect } from "react"; diff --git a/src/bootstrap/DownloadButton.md b/src/bootstrap/DownloadButton.md index e70e3d6..30066f5 100644 --- a/src/bootstrap/DownloadButton.md +++ b/src/bootstrap/DownloadButton.md @@ -5,6 +5,6 @@ Firefox. See [related issue](https://bugzilla.mozilla.org/show_bug.cgi?id=858538) for more details. -```js +```jsx Download ``` diff --git a/src/bootstrap/EmailInput.md b/src/bootstrap/EmailInput.md index 1178756..fcb22ae 100644 --- a/src/bootstrap/EmailInput.md +++ b/src/bootstrap/EmailInput.md @@ -4,10 +4,12 @@ checking. It's only meaningful using inside `
`. All additional `props` are passed to the `` HTML component. -```js +```jsx import { useState } from "react"; import Button from "./Button"; + const [email, setEmail] = useState("Wrong email"); + e.preventDefault()}> ` HTML component. -```js +```jsx import { useState } from "react"; const [files, setFiles] = useState([]); @@ -23,7 +23,7 @@ const label = files.length === 1 ? files[0].name : "Choose file"; ### FileInput with multiple files -```js +```jsx import { useState } from "react"; const [files, setFiles] = useState([]); diff --git a/src/bootstrap/Modal.md b/src/bootstrap/Modal.md index 08d4878..7e70b6d 100644 --- a/src/bootstrap/Modal.md +++ b/src/bootstrap/Modal.md @@ -6,9 +6,9 @@ the page since modals are rendered in portals. Modals also have three optional sizes, which can be defined through the `size` prop: -- small - `sm` -- large - `lg` -- extra-large - `xl` +- small - `sm` +- large - `lg` +- extra-large - `xl` For more details please visit Bootstrap @@ -18,7 +18,7 @@ documentation. diff --git a/src/form/components/ForisForm.md b/src/form/components/ForisForm.md index c6cdc91..c030b22 100644 --- a/src/form/components/ForisForm.md +++ b/src/form/components/ForisForm.md @@ -6,26 +6,30 @@ comfort API and allows to create typical Foris module forms easily. You can pass more forms as children. -```js - - - - - +```jsx static +export default function WAN({ ws }) { + return ( + + + + + + ); +} ``` ### Example of children forms `props` usage -```js +```jsx static export default function MACForm({ formData, formErrors, @@ -64,9 +68,9 @@ export default function MACForm({ } ``` -The passes subsequent `props` to the child components. +The `` passes subsequent `props` to the child components. -| Prop | Type | Description | +| Prop name | Type | Description | | -------------- | ------ | -------------------------------------------------------------------------- | | `formData` | object | Data returned from API. | | `formErrors` | object | Errors returned after validation via validator. | diff --git a/src/form/components/SubmitButton.js b/src/form/components/SubmitButton.js index f567569..ce54b83 100644 --- a/src/form/components/SubmitButton.js +++ b/src/form/components/SubmitButton.js @@ -18,8 +18,11 @@ export const STATES = { }; SubmitButton.propTypes = { + /** Disable button */ disabled: PropTypes.bool, + /** Button state */ state: PropTypes.oneOf(Object.keys(STATES).map((key) => STATES[key])), + /** Button label */ label: PropTypes.string, }; @@ -34,7 +37,7 @@ export function SubmitButton({ disabled, state, label, ...props }) { labelSubmitButton = _("Updating"); break; case STATES.LOAD: - labelSubmitButton = _("Load settings"); + labelSubmitButton = _("Loading"); break; default: labelSubmitButton = _("Save"); diff --git a/src/form/components/SubmitButton.md b/src/form/components/SubmitButton.md new file mode 100644 index 0000000..9c8f8aa --- /dev/null +++ b/src/form/components/SubmitButton.md @@ -0,0 +1,12 @@ +SubmitButton is a component that renders a button with different states based on +the `state` prop. It can be used to indicate the status of a form submission. + +```jsx padded + + + + + + + +``` diff --git a/styleguide.config.js b/styleguide.config.js index fdd8e62..5778347 100644 --- a/styleguide.config.js +++ b/styleguide.config.js @@ -1,10 +1,11 @@ /* - * Copyright (C) 2019-2022 CZ.NIC z.s.p.o. (https://www.nic.cz/) + * Copyright (C) 2019-2025 CZ.NIC z.s.p.o. (https://www.nic.cz/) * * This is free software, licensed under the GNU General Public License v3. * See /LICENSE for more information. */ const path = require("path"); + const pjson = require("./package.json"); module.exports = { @@ -15,6 +16,50 @@ module.exports = { link: "#0075a3", linkHover: "#00a2e2", }, + fontFamily: { + base: '"Roboto", sans-serif', + }, + sidebarWidth: 255, + }, + template: { + favicon: "/docs/components/logo.svg", + head: { + links: [ + { + rel: "stylesheet", + href: "https://fonts.googleapis.com/css?family=Roboto", + }, + ], + }, + }, + styles: { + StyleGuide: { + logo: { + display: "flex", + alignItems: "center", + }, + }, + Logo: { + logo: { + display: "inline-flex", + }, + }, + Version: { + version: { + display: "inline-flex", + margin: "none", + marginLeft: "8px", + fontSize: "0.6rem", + fontWeight: "bold", + padding: "0.1rem 0.2rem", + color: "#fff", + backgroundColor: "#6c757d", + borderRadius: "5px", + textAlign: "center", + verticalAlign: "middle", + whiteSpace: "nowrap", + }, + }, }, tocMode: "collapse", pagePerSection: true, @@ -77,9 +122,6 @@ module.exports = { usageMode: "expand", }, ], - template: { - favicon: "/docs/components/logo.svg", - }, require: [ "babel-polyfill", path.join(__dirname, "src/testUtils/mockGlobals.js"),