From 880803ee2e77748144da35599077d61fe3706cb7 Mon Sep 17 00:00:00 2001 From: Cagatay Civici Date: Fri, 4 Nov 2022 20:07:42 +0300 Subject: [PATCH] New Chips Docs --- components/doc/chips/apidoc.js | 325 +++++++++++++++ components/doc/chips/basicdoc.js | 50 +++ components/doc/chips/disableddoc.js | 41 ++ components/doc/chips/floatlabeldoc.js | 62 +++ components/doc/chips/importdoc.js | 17 + components/doc/chips/index.js | 547 -------------------------- components/doc/chips/invaliddoc.js | 41 ++ components/doc/chips/keyfilterdoc.js | 51 +++ components/doc/chips/separatordoc.js | 50 +++ components/doc/chips/templatedoc.js | 75 ++++ pages/chips/index.js | 80 +++- 11 files changed, 775 insertions(+), 564 deletions(-) create mode 100644 components/doc/chips/apidoc.js create mode 100644 components/doc/chips/basicdoc.js create mode 100644 components/doc/chips/disableddoc.js create mode 100644 components/doc/chips/floatlabeldoc.js create mode 100644 components/doc/chips/importdoc.js delete mode 100644 components/doc/chips/index.js create mode 100644 components/doc/chips/invaliddoc.js create mode 100644 components/doc/chips/keyfilterdoc.js create mode 100644 components/doc/chips/separatordoc.js create mode 100644 components/doc/chips/templatedoc.js diff --git a/components/doc/chips/apidoc.js b/components/doc/chips/apidoc.js new file mode 100644 index 0000000000..d1d792b1a4 --- /dev/null +++ b/components/doc/chips/apidoc.js @@ -0,0 +1,325 @@ +import Link from 'next/link'; +import { CodeHighlight } from '../common/codehighlight'; +import { DevelopmentSection } from '../common/developmentsection'; +import { DocSectionText } from '../common/docsectiontext'; + +export function ApiDoc(props) { + return ( + <> + +

Properties

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefaultDescription
idstringnullUnique identifier of the component.
inputIdstringnullIdentifier of the focus input to match a label defined for the chips.
namestringnullName of the input field.
placeholderstringnullAdvisory information to display on input.
valuearraynullValue of the component.
maxnumbernullMaximum number of entries allowed.
disabledbooleanfalseWhen present, it specifies that the element should be disabled.
readOnlybooleanfalseWhen present, it specifies that the element should be read-only.
removablebooleantrueWhether an item is removable.
stylestringnullInline style of the element.
classNamestringnullStyle class of the element.
tooltipanynullContent of the tooltip.
tooltipOptionsobjectnullConfiguration of the tooltip, refer to the tooltip documentation for more information.
ariaLabelledBystringnullEstablishes relationships between the component and label(s) where its value should be one or more element IDs.
allowDuplicatebooleantrueWhether to allow duplicate values or not.
separatorstringnullSeparator char to add an item when pressed in addition to the enter key. Currently only possible value is ","
itemTemplatefunctionnullTemplate function to return the content of a chip.
keyfilterstring/regexnullFormat definition of the keys to block.
addOnBlurbooleannullWhether to add an item when the input loses focus.
+
+ +

Events

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameParametersDescription
onChange + originalEvent: Browser event
+ value: New value of the component + 		Callback to invoke when a chip is added or removed.
onAdd + originalEvent: Browser event
+ value: Added item value + 		Callback to invoke when a chip is added. Return 'false' to prevent the item from being added.
onRemove + originalEvent: Browser event
+ value: Removed item value + 		Callback to invoke when a chip is removed.
onFocusevent: Browser eventCallback to invoke when the component gets focus.
onBlurevent: Browser eventCallback to invoke when the component loses focus.
onKeyDownevent: Browser event.Callback to invoke when the key pressed.
+
+ +

Styling

+

+ Following is the list of structural style classes, for theming classes visit theming page. +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameElement
p-chipsContainer element
p-chips-tokenChip element container.
p-chips-token-iconIcon of a chip.
p-chips-token-labellabel of a chip.
p-chips-input-tokenContainer of input element.
+
+ +

Accessibility

+ +

Screen Reader

+

+ Value to describe the component can either be provided via label tag combined with inputId prop or using aria-labelledby, aria-label props. Chip list uses listbox role with{' '} + aria-orientation set to horizontal whereas each chip has the option role with aria-label set to the label of the chip. +

+ + {` + + + +Tags + + + +`} + + +

Input Field Keyboard Support

+
+ + + + + + + + + + + + + + + + + + + + + + + + + +
KeyFunction
+ tab + Moves focus to the input element
+ enter + Adds a new chips using the input field value.
+ backspace + Deletes the previous chip if the input field is empty.
+ left arrow + Moves focus to the previous chip if available and input field is empty.
+
+ +

Chip Keyboard Support

+
+ + + + + + + + + + + + + + + + + + + + + +
KeyFunction
+ left arrow + Moves focus to the previous chip if available.
+ right arrow + Moves focus to the next chip, if there is none then input field receives the focus.
+ backspace + Deletes the chips and adds focus to the input field.
+
+ + +

Dependencies

+

None.

+ + ); +} diff --git a/components/doc/chips/basicdoc.js b/components/doc/chips/basicdoc.js new file mode 100644 index 0000000000..5668bdeb7d --- /dev/null +++ b/components/doc/chips/basicdoc.js @@ -0,0 +1,50 @@ +import { useState } from 'react'; +import { Chips } from '../../lib/chips/Chips'; +import { DocSectionText } from '../common/docsectiontext'; +import { DocSectionCode } from '../common/docsectioncode'; + +export function BasicDoc(props) { + const [value, setValue] = useState([]); + + const code = { + basic: ` + setValue(e.value)} /> + `, + javascript: ` +import { useState } from "react"; +import { Chips } from "primereact/chips"; + +export default function BasicDemo() { + const [value, setValue] = useState([]); + + return ( + setValue(e.value)} /> + ) +} + `, + typescript: ` +import { useState } from "react"; +import { Chips } from "primereact/chips"; + +export default function BasicDemo() { + const [value, setValue] = useState([]); + + return ( + setValue(e.value)} /> + ) +} + ` + }; + + return ( + <> + + Chips requires an array as its value and onChange callback to update the model. + +
+ setValue(e.value)} /> +
+ + + ); +} diff --git a/components/doc/chips/disableddoc.js b/components/doc/chips/disableddoc.js new file mode 100644 index 0000000000..f4657da829 --- /dev/null +++ b/components/doc/chips/disableddoc.js @@ -0,0 +1,41 @@ +import { Chips } from '../../lib/chips/Chips'; +import { DocSectionText } from '../common/docsectiontext'; +import { DocSectionCode } from '../common/docsectioncode'; + +export function DisabledDoc(props) { + const code = { + basic: ` + + `, + javascript: ` +import { Chips } from "primereact/chips"; + +export default function DisabledDemo() { + return ( + + ) +} + `, + typescript: ` +import { Chips } from "primereact/chips"; + +export default function DisabledDemo() { + return ( + + ) +} + ` + }; + + return ( + <> + + disabled prop prevents an input from being editable. + +
+ +
+ + + ); +} diff --git a/components/doc/chips/floatlabeldoc.js b/components/doc/chips/floatlabeldoc.js new file mode 100644 index 0000000000..d09598e222 --- /dev/null +++ b/components/doc/chips/floatlabeldoc.js @@ -0,0 +1,62 @@ +import { useState } from 'react'; +import { Chips } from '../../lib/chips/Chips'; +import { DocSectionText } from '../common/docsectiontext'; +import { DocSectionCode } from '../common/docsectioncode'; + +export function FloatLabelDoc(props) { + const [value, setValue] = useState([]); + + const code = { + basic: ` + + setValue(e.value)} /> + + + `, + javascript: ` +import { useState } from "react"; +import { Chips } from "primereact/chips"; + +export default function FloatLabelDemo() { + const [value, setValue] = useState([]); + + return ( + + setValue(e.value)} /> + + + ) +} + `, + typescript: ` +import { useState } from "react"; +import { Chips } from "primereact/chips"; + +export default function FloatLabelDemo() { + const [value, setValue] = useState([]); + + return ( + + setValue(e.value)} /> + + + ) +} + ` + }; + + return ( + <> + + A floating label is implemented by wrapping the input and the label inside a container having .p-float-label style class. + +
+ + setValue(e.value)} /> + + +
+ + + ); +} diff --git a/components/doc/chips/importdoc.js b/components/doc/chips/importdoc.js new file mode 100644 index 0000000000..1679c2e2f7 --- /dev/null +++ b/components/doc/chips/importdoc.js @@ -0,0 +1,17 @@ +import { DocSectionText } from '../common/docsectiontext'; +import { DocSectionCode } from '../common/docsectioncode'; + +export function ImportDoc(props) { + const code = { + basic: ` +import { Chips } from 'primereact/chips'; + ` + }; + + return ( + <> + + + + ); +} diff --git a/components/doc/chips/index.js b/components/doc/chips/index.js deleted file mode 100644 index 5bbee6bcc7..0000000000 --- a/components/doc/chips/index.js +++ /dev/null @@ -1,547 +0,0 @@ -import React, { memo } from 'react'; -import Link from 'next/link'; -import { TabView, TabPanel } from '../../lib/tabview/TabView'; -import { useLiveEditorTabs } from '../common/liveeditor'; -import { CodeHighlight } from '../common/codehighlight'; -import { DevelopmentSection } from '../common/developmentsection'; - -export const ChipsDoc = memo(() => { - const sources = { - class: { - tabName: 'Class Source', - content: ` -import React, { Component } from 'react'; -import { Chips } from 'primereact/chips'; - -export class ChipsDemo extends Component { - - constructor(props) { - super(props); - this.state = { - values1: [], - values2: [], - values3: [] - }; - } - - customChip(item) { - return ( -
- {item} - (active) - -
- ); - } - - render() { - return ( -
-
-
Basic
- this.setState({ values1: e.value })} /> - -
Comma Separator
- this.setState({ values2: e.value })} separator="," /> - -
Template
- this.setState({ values3: e.value })} max={5} itemTemplate={this.customChip}> -
-
- ) - } -} - ` - }, - hooks: { - tabName: 'Hooks Source', - content: ` -import React, { useState } from 'react'; -import { Chips } from 'primereact/chips'; - -const ChipsDemo = () => { - const [values1, setValues1] = useState([]); - const [values2, setValues2] = useState([]); - const [values3, setValues3] = useState([]); - - const customChip = (item) => { - return ( -
f - {item} - (active) - -
- ); - } - - return ( -
-
-
Basic
- setValues1(e.value)} /> - -
Comma Separator
- setValues2(e.value)} separator="," /> - -
Template
- setValues3(e.value)} max={5} itemTemplate={customChip}> -
-
- ) -} - ` - }, - ts: { - tabName: 'TS Source', - content: ` -import React, { useState } from 'react'; -import { Chips } from 'primereact/chips'; - -const ChipsDemo = () => { - const [values1, setValues1] = useState([]); - const [values2, setValues2] = useState([]); - const [values3, setValues3] = useState([]); - - const customChip = (item: any) => { - return ( -
- {item} - (active) - -
- ); - } - - return ( -
-
-
Basic
- setValues1(e.value)} /> - -
Comma Separator
- setValues2(e.value)} separator="," /> - -
Template
- setValues3(e.value)} max={5} itemTemplate={customChip}> -
-
- ) -} - ` - }, - browser: { - tabName: 'Browser Source', - imports: ` - - `, - content: ` -const { useState, useRef } = React; -const { Chips } = primereact.chips; - -const ChipsDemo = () => { - const [values1, setValues1] = useState([]); - const [values2, setValues2] = useState([]); - const [values3, setValues3] = useState([]); - - const customChip = (item) => { - return ( -
- {item} - (active) - -
- ); - } - - return ( -
-
-
Basic
- setValues1(e.value)} /> - -
Comma Separator
- setValues2(e.value)} separator="," /> - -
Template
- setValues3(e.value)} max={5} itemTemplate={customChip}> -
-
- ) -} - ` - } - }; - - return ( -
- - -
Import via Module
- - {` -import { Chips } from 'primereact/chips'; -`} - - -
Import via CDN
- - {` - - -`} - - -
Getting Started
-

- Chips requires an array as its value and onChange callback to update the model. -

- - - {` - setValue(e.value)}> -`} - - -
Custom Content
-

- A chip is customized using itemTemplate function where value is passed to return JSX. -

- - {` - setValue(e.value)} itemTemplate={customChip}> -`} - - - {` -customChip(item) { - return ( -
- {item} - (active) - -
- ); -} - -`} - -
KeyFilter
-

- Chips has built-in key filtering support to block certain keys, refer to keyfilter page for more information. -

- -
Properties
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDescription
idstringnullUnique identifier of the component.
inputIdstringnullIdentifier of the focus input to match a label defined for the chips.
namestringnullName of the input field.
placeholderstringnullAdvisory information to display on input.
valuearraynullValue of the component.
maxnumbernullMaximum number of entries allowed.
disabledbooleanfalseWhen present, it specifies that the element should be disabled.
readOnlybooleanfalseWhen present, it specifies that the element should be read-only.
removablebooleantrueWhether an item is removable.
stylestringnullInline style of the element.
classNamestringnullStyle class of the element.
tooltipanynullContent of the tooltip.
tooltipOptionsobjectnullConfiguration of the tooltip, refer to the tooltip documentation for more information.
ariaLabelledBystringnullEstablishes relationships between the component and label(s) where its value should be one or more element IDs.
allowDuplicatebooleantrueWhether to allow duplicate values or not.
separatorstringnullSeparator char to add an item when pressed in addition to the enter key. Currently only possible value is ","
itemTemplatefunctionnullTemplate function to return the content of a chip.
keyfilterstring/regexnullFormat definition of the keys to block.
addOnBlurbooleannullWhether to add an item when the input loses focus.
-
- -
Events
-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameParametersDescription
onChange - originalEvent: Browser event
- value: New value of the component - 		Callback to invoke when a chip is added or removed.
onAdd - originalEvent: Browser event
- value: Added item value - 		Callback to invoke when a chip is added. Return 'false' to prevent the item from being added.
onRemove - originalEvent: Browser event
- value: Removed item value - 		Callback to invoke when a chip is removed.
onFocusevent: Browser eventCallback to invoke when the component gets focus.
onBlurevent: Browser eventCallback to invoke when the component loses focus.
onKeyDownevent: Browser event.Callback to invoke when the key pressed.
-
- -
Styling
-

- Following is the list of structural style classes, for theming classes visit theming page. -

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameElement
p-chipsContainer element
p-chips-tokenChip element container.
p-chips-token-iconIcon of a chip.
p-chips-token-labellabel of a chip.
p-chips-input-tokenContainer of input element.
-
- -
Accessibility
- -
Screen Reader
-

- Value to describe the component can either be provided via label tag combined with inputId prop or using aria-labelledby, aria-label props. Chip list uses listbox role with{' '} - aria-orientation set to horizontal whereas each chip has the option role with aria-label set to the label of the chip. -

- - {` - - - -Tags - - - -`} - -
Input Field Keyboard Support
-
- - - - - - - - - - - - - - - - - - - - - - - - - -
KeyFunction
- tab - Moves focus to the input element
- enter - Adds a new chips using the input field value.
- backspace - Deletes the previous chip if the input field is empty.
- left arrow - Moves focus to the previous chip if available and input field is empty.
-
- -
Chip Keyboard Support
-
- - - - - - - - - - - - - - - - - - - - - -
KeyFunction
- left arrow - Moves focus to the previous chip if available.
- right arrow - Moves focus to the next chip, if there is none then input field receives the focus.
- backspace - Deletes the chips and adds focus to the input field.
-
- -
Dependencies
-

None.

- - - {useLiveEditorTabs({ name: 'ChipsDemo', sources: sources })} - -
- ); -}); - -export default ChipsDoc; diff --git a/components/doc/chips/invaliddoc.js b/components/doc/chips/invaliddoc.js new file mode 100644 index 0000000000..ce2468c772 --- /dev/null +++ b/components/doc/chips/invaliddoc.js @@ -0,0 +1,41 @@ +import { Chips } from '../../lib/chips/Chips'; +import { DocSectionText } from '../common/docsectiontext'; +import { DocSectionCode } from '../common/docsectioncode'; + +export function InvalidDoc(props) { + const code = { + basic: ` + + `, + javascript: ` +import { Chips } from "primereact/chips"; + +export default function InvalidDemo() { + return ( + + ) +} + `, + typescript: ` +import { Chips } from "primereact/chips"; + +export default function InvalidDemo() { + return ( + + ) +} + ` + }; + + return ( + <> + + Applying p-invalid class to an input element indicates a failed validation. + +
+ +
+ + + ); +} diff --git a/components/doc/chips/keyfilterdoc.js b/components/doc/chips/keyfilterdoc.js new file mode 100644 index 0000000000..765075e392 --- /dev/null +++ b/components/doc/chips/keyfilterdoc.js @@ -0,0 +1,51 @@ +import { useState } from 'react'; +import Link from 'next/link'; +import { Chips } from '../../lib/chips/Chips'; +import { DocSectionText } from '../common/docsectiontext'; +import { DocSectionCode } from '../common/docsectioncode'; + +export function KeyFilterDoc(props) { + const [value, setValue] = useState([]); + + const code = { + basic: ` + setValue(e.value)} keyfilter="int" /> + `, + javascript: ` +import { useState } from "react"; +import { Chips } from "primereact/chips"; + +export default function KeyFilterDemo() { + const [value, setValue] = useState([]); + + return ( + setValue(e.value)} keyfilter="int" /> + ) +} + `, + typescript: ` +import { useState } from "react"; +import { Chips } from "primereact/chips"; + +export default function KeyFilterDemo() { + const [value, setValue] = useState([]); + + return ( + setValue(e.value)} keyfilter="int" /> + ) +} + ` + }; + + return ( + <> + + Chips has built-in key filtering support to block certain keys, refer to keyfilter page for more information. + +
+ setValue(e.value)} keyfilter="int" /> +
+ + + ); +} diff --git a/components/doc/chips/separatordoc.js b/components/doc/chips/separatordoc.js new file mode 100644 index 0000000000..6150aed274 --- /dev/null +++ b/components/doc/chips/separatordoc.js @@ -0,0 +1,50 @@ +import { useState } from 'react'; +import { Chips } from '../../lib/chips/Chips'; +import { DocSectionText } from '../common/docsectiontext'; +import { DocSectionCode } from '../common/docsectioncode'; + +export function SeparatorDoc(props) { + const [value, setValue] = useState([]); + + const code = { + basic: ` + setValue(e.value)} separator="," /> + `, + javascript: ` +import { useState } from "react"; +import { Chips } from "primereact/chips"; + +export default function SeparatorDemo() { + const [value, setValue] = useState([]); + + return ( + setValue(e.value)} separator="," /> + ) +} + `, + typescript: ` +import { useState } from "react"; +import { Chips } from "primereact/chips"; + +export default function SeparatorDemo() { + const [value, setValue] = useState([]); + + return ( + setValue(e.value)} separator="," /> + ) +} + ` + }; + + return ( + <> + + A new chip is added when enter key is pressed, separator property allows definining an additional key. Currently only valid value is , to create a new item when comma key is pressed. + +
+ setValue(e.value)} separator="," /> +
+ + + ); +} diff --git a/components/doc/chips/templatedoc.js b/components/doc/chips/templatedoc.js new file mode 100644 index 0000000000..d8f79ff708 --- /dev/null +++ b/components/doc/chips/templatedoc.js @@ -0,0 +1,75 @@ +import { useState } from 'react'; +import { Chips } from '../../lib/chips/Chips'; +import { DocSectionText } from '../common/docsectiontext'; +import { DocSectionCode } from '../common/docsectioncode'; + +export function TemplateDoc(props) { + const [value, setValue] = useState([]); + + const customChip = (item) => { + return ( +
+ {item} - (active) + +
+ ); + }; + + const code = { + basic: ` + setValue(e.value)} itemTemplate={customChip} /> + `, + javascript: ` +import { useState } from "react"; +import { Chips } from "primereact/chips"; + +export default function TemplateDemo() { + const [value, setValue] = useState([]); + const customChip = (item) => { + return ( +
+ {item} - (active) + +
+ ); + }; + + return ( + setValue(e.value)} itemTemplate={customChip} /> + ) +} + `, + typescript: ` +import { useState } from "react"; +import { Chips } from "primereact/chips"; + +export default function TemplateDemo() { + const [value, setValue] = useState([]); + const customChip = (item: any) => { + return ( +
+ {item} - (active) + +
+ ); + }; + + return ( + setValue(e.value)} itemTemplate={customChip} /> + ) +} + ` + }; + + return ( + <> + + A chip is customized using itemTemplate function where value is passed to return JSX. + +
+ setValue(e.value)} itemTemplate={customChip}/> +
+ + + ); +} diff --git a/pages/chips/index.js b/pages/chips/index.js index 175ef6c6f1..367ebefbe8 100644 --- a/pages/chips/index.js +++ b/pages/chips/index.js @@ -1,10 +1,66 @@ import React, { useState } from 'react'; -import { Chips } from '../../components/lib/chips/Chips'; -import ChipsDoc from '../../components/doc/chips'; -import { DocActions } from '../../components/doc/common/docactions'; import Head from 'next/head'; +import { DocSectionNav } from '../../components/doc/common/docsectionnav'; +import { DocSections } from '../../components/doc/common/docsections'; +import { ImportDoc } from '../../components/doc/chips/importdoc'; +import { BasicDoc } from '../../components/doc/chips/basicdoc'; +import { FloatLabelDoc } from '../../components/doc/chips/floatlabeldoc'; +import { InvalidDoc } from '../../components/doc/chips/invaliddoc'; +import { DisabledDoc } from '../../components/doc/chips/disableddoc'; +import { SeparatorDoc } from '../../components/doc/chips/separatordoc'; +import { TemplateDoc } from '../../components/doc/chips/templatedoc'; +import { KeyFilterDoc } from '../../components/doc/chips/keyfilterdoc'; +import { ApiDoc } from '../../components/doc/chips/apidoc'; const ChipsDemo = () => { + const docs = [ + { + id: 'import', + label: 'Import', + component: ImportDoc + }, + { + id: 'basic', + label: 'Basic', + component: BasicDoc + }, + { + id: 'floatlabel', + label: 'Float Label', + component: FloatLabelDoc + }, + { + id: 'invalid', + label: 'Invalid', + component: InvalidDoc + }, + { + id: 'disabled', + label: 'Disabled', + component: DisabledDoc + }, + { + id: 'separator', + label: 'Separator', + component: SeparatorDoc + }, + { + id: 'template', + label: 'Template', + component: TemplateDoc + }, + { + id: 'keyfilter', + label: 'Key Filter', + component: KeyFilterDoc + }, + { + id: 'apidoc', + label: 'API', + component: ApiDoc + } + ]; + const [values1, setValues1] = useState([]); const [values2, setValues2] = useState([]); const [values3, setValues3] = useState([]); @@ -24,28 +80,18 @@ const ChipsDemo = () => { React Chips Component +

Chips

Chips is used to enter multiple values on an input field.

-
-
-
-
Basic
- setValues1(e.value)} /> - -
Comma Separator
- setValues2(e.value)} separator="," /> - -
Template
- setValues3(e.value)} max={5} itemTemplate={customChip}> -
+
+ +
- -
); };