Merge pull request #138 from wpmudev/selector-documentation

Selector

packages/components/selector/src/selector.option.tsx

@@ -3,6 +3,7 @@ import React from "react"
 import { Tooltip } from "@wpmudev/sui-tooltip"
 import { generateCN } from "@wpmudev/sui-utils"
 import { useInteraction } from "@wpmudev/sui-hooks"
+import { Tag } from "@wpmudev/sui-tag"
 import * as Icons from "@wpmudev/sui-icons"
 
 import { SelectorOptionProps } from "./selector.types"
@@ -17,6 +18,8 @@ const SelectorOption: React.FC<SelectorOptionProps> = ({
 	tag,
 	allowRemove,
 	onRemove,
+	isPro,
+	tagColor,
 }) => {
 	// Custom hook to handle interaction states (hover, focus, etc.)
 	const [isHovered, isFocused, methods] = useInteraction({})
@@ -51,7 +54,7 @@ const SelectorOption: React.FC<SelectorOptionProps> = ({
 					data-testid="selector-remove"
 				>
 					<Tooltip
-						type="button"
+						type="icon"
 						icon="trash"
 						iconSize="sm"
 						appearance="primary"
@@ -67,7 +70,7 @@ const SelectorOption: React.FC<SelectorOptionProps> = ({
 					</Tooltip>
 				</div>
 			)}
-			{["icon-only"].includes(variation ?? "") && !!tag && tag}
+
 			{/* Display icon and title/header if either iconOrBrandUrl or title is provided */}
 			{(!!iconOrBrandUrl || !!title) && (
 				<div className="sui-selector__option-header">
@@ -87,7 +90,21 @@ const SelectorOption: React.FC<SelectorOptionProps> = ({
 					{!!title && !["icon-only"].includes(variation ?? "") && (
 						<div className="sui-selector__option-header-title">
 							<span>{title}</span>
-							{!!tag && tag}
+							{isPro && (
+								<Tag
+									design="outlined"
+									color="black"
+									isSmall={true}
+									isUppercase={true}
+								>
+									Pro
+								</Tag>
+							)}
+							{!!tag && !isPro && (
+								<Tag style="truncated" color={tagColor}>
+									{tag}
+								</Tag>
+							)}
 						</div>
 					)}
 				</div>

packages/components/selector/src/selector.tsx

@@ -23,6 +23,14 @@ const Selector: React.FC<SelectorProps> = forwardRef<
 			alignment = "center",
 			variation = "default",
 			onChange = () => {},
+			onRemove = () => {},
+			allowRemove = false,
+			tag,
+			iconOrBrandUrl,
+			imageUrl,
+			title,
+			description,
+			tagColor,
 			...props
 		}: SelectorProps,
 		ref,
@@ -72,21 +80,18 @@ const Selector: React.FC<SelectorProps> = forwardRef<
 				/>
 				<SelectorOption
 					{...props}
+					tagColor={tagColor}
+					allowRemove={allowRemove}
+					onRemove={onRemove}
+					tag={tag}
+					iconOrBrandUrl={iconOrBrandUrl}
+					imageUrl={imageUrl}
 					isChecked={isChecked}
+					title={title}
+					description={description}
 					alignment={alignment ?? "left"}
 					variation={variation ?? "default"}
-					{...(isPro && {
-						tag: (
-							<Tag
-								design="outlined"
-								color="black"
-								isSmall={true}
-								isUppercase={true}
-							>
-								Pro
-							</Tag>
-						),
-					})}
+					isPro={isPro}
 				/>
 				{label && <span className="sui-screen-reader-only">{label}</span>}
 			</label>

packages/components/selector/src/selector.types.ts

@@ -39,6 +39,16 @@ interface SelectorProps
 	allowRemove?: boolean
 	/** Event handler for removing the Selector */
 	onRemove?(name: string, value: string | number): void
+	/** Specifiy the color of the tag */
+	tagColor:
+		| "default"
+		| "blue"
+		| "yellow"
+		| "red"
+		| "green"
+		| "white"
+		| "black"
+		| "navy"
 }
 
 interface SelectorOptionProps
@@ -54,6 +64,7 @@ interface SelectorOptionProps
 		| "tag"
 		| "allowRemove"
 		| "onRemove"
+		| "tagColor"
 	> {}
 
 export type { SelectorProps, SelectorOptionProps }

packages/components/selector/stories/selector.mdx

@@ -1,13 +1,24 @@
-import { Page, Section } from '@wpmudev/storybook';
-import { Unstyled } from '@storybook/blocks';
+import { Page } from "@wpmudev/storybook"
+import { Unstyled } from "@storybook/blocks"
+
+import TabUsage from "./tabs/TabUsage.mdx"
+import TabCode from "./tabs/TabCode.mdx"
+import TabExamples from "./tabs/TabExamples.mdx"
 
 <Unstyled>
-	<Section title="Shhh... Not much to see here at the moment, but stay tuned!" contained={true}>
-		<p>
-			Quiet for now, but get ready! Exciting stuff is coming. Our developers are working really hard behind the scenes to make it happen. Stay curious and excited! 🌟👷
-		</p>
-		<p>
-			In the meantime, feel free to explore our demo page for this component.
-		</p>
-	</Section>
+	<Page.Tabs
+		title="Selector"
+		subtitle="The selector is a block that provides organised options to users."
+		status="draft"
+	>
+		<div id="usage" label="Usage">
+			<TabUsage />
+		</div>
+		<div id="code" label="Code">
+			<TabCode />
+		</div>
+		<div id="examples" label="Examples">
+			<TabExamples />
+		</div>
+	</Page.Tabs>
 </Unstyled>

packages/components/selector/stories/selector.stories.tsx

@@ -40,15 +40,15 @@ const options = [
 
 // Build story
 export const Selector = ({ variation, ...args }) => {
-	const [val, setVal] = useState("")
+	const [val, setVal] = useState<number>()
 
 	const boxStyles = {
 		padding: 20,
 		borderRadius: 4,
 		// background: "#fff",
 	}
 
-	const onChange = (isChecked, value, name) => {
+	const onChange = (_isChecked: boolean, value: number, _name: string) => {
 		setVal(value)
 	}
 
@@ -68,6 +68,7 @@ export const Selector = ({ variation, ...args }) => {
 									onChange={onChange}
 									isChecked={val === option.value}
 									variation={variation}
+									label={option.name}
 									{...args}
 								/>
 							</Col>
@@ -90,6 +91,8 @@ Selector.args = {
 	allowRemove: false,
 	isDisabled: false,
 	isPro: true,
+	tag: "Tag",
+	tagColor: "default",
 }
 
 // Story props settings
@@ -160,4 +163,30 @@ Selector.argTypes = {
 			},
 		},
 	},
+	tagColor: {
+		name: "Tag Color",
+		options: [
+			"default",
+			"blue",
+			"navy",
+			"yellow",
+			"red",
+			"green",
+			"black",
+			"white",
+		],
+		control: {
+			type: "select",
+			labels: {
+				"": "Default",
+				blue: "Blue (Information)",
+				navy: "Navy Blue",
+				yellow: "Yellow (Warning)",
+				red: "Red (Error)",
+				green: "Green (Success)",
+				black: "Black",
+				white: "White",
+			},
+		},
+	},
 }

packages/components/selector/stories/tabs/Examples/Alignment.mdx

@@ -0,0 +1,41 @@
+import { Section, Preview, Snippet } from "@wpmudev/storybook"
+import { Selector } from "../../../src"
+import dedent from "dedent"
+
+export const leftCode = dedent`
+   <Selector alignment="left" title="Option 1" iconOrBrandUrl="Bell" />
+`
+
+export const centerCode = dedent`
+   <Selector alignment="center" title="Option 1" iconOrBrandUrl="Bell" />
+`
+
+<Section
+    title="Left"
+    contained={true}
+    border={true}
+    style={{ paddingRight: 0, paddingLeft: 0 }}
+>
+    <Preview wrapper={true}>
+    	<div style={{ padding: 50 }}>
+			<Selector alignment="left" title="Option 1" iconOrBrandUrl="Bell" />
+		</div>
+    </Preview>
+    <Snippet language="js">{leftCode}</Snippet>
+
+</Section>
+
+<Section
+    title="Center"
+    contained={true}
+    border={true}
+    style={{ paddingRight: 0, paddingLeft: 0 }}
+>
+    <Preview wrapper={true}>
+    	<div style={{ padding: 50 }}>
+			<Selector alignment="center" title="Option 1" iconOrBrandUrl="Bell" />
+		</div>
+    </Preview>
+    <Snippet language="js">{centerCode}</Snippet>
+
+</Section>

packages/components/selector/stories/tabs/Examples/States.mdx

@@ -0,0 +1,125 @@
+import { Section, Preview, Snippet, Code } from "@wpmudev/storybook"
+import { Selector } from "../../../src"
+import dedent from "dedent"
+
+export const disabledCode = dedent`
+  <Selector
+    isDisabled={true}
+    variation="compound"
+    title="Option 1"
+    description="Lorem ipsum dolor sit amet, consectetur adipisicing elit."
+    iconOrBrandUrl="Bell"
+  />
+`
+
+export const allowRemoveCode = dedent`
+  <Selector
+    allowRemove={true}
+    variation="compound"
+    title="Option 1"
+    description="Lorem ipsum dolor sit amet, consectetur adipisicing elit."
+    iconOrBrandUrl="Bell"
+  />
+`
+
+export const proVersion = dedent`
+  <Selector
+    isPro={true}
+    variation="compound"
+    title="Option 1"
+    description="Lorem ipsum dolor sit amet, consectetur adipisicing elit."
+    iconOrBrandUrl="Bell"
+  />
+`
+
+export const customTagCode = dedent`
+  <Selector
+    tag="New"
+    tagColor="green"
+    variation="compound"
+    title="Option 1"
+    description="Lorem ipsum dolor sit amet, consectetur adipisicing elit."
+    iconOrBrandUrl="Bell"
+  />
+`
+
+<Section
+	title="Disabled"
+	contained={true}
+	border={true}
+	style={{ paddingRight: 0, paddingLeft: 0 }}
+>
+	<Preview wrapper={true}>
+		<Selector
+			isDisabled={true}
+			variation="compound"
+			title="Option 1"
+			description="Lorem ipsum dolor sit amet, consectetur adipisicing elit."
+			iconOrBrandUrl="Bell"
+		/>
+	</Preview>
+	<Snippet language="js">{disabledCode}</Snippet>
+</Section>
+
+<Section
+	title="Allow Remove"
+	contained={true}
+	border={true}
+	style={{ paddingRight: 0, paddingLeft: 0 }}
+>
+	<p>
+		When <Code small={true}>allowRemove</Code> is set to{" "}
+		<Code small={true}>true</Code>, a button for deletion will appear on hover
+	</p>
+	<Preview wrapper={true}>
+		<Selector
+			allowRemove={true}
+			variation="compound"
+			title="Option 1"
+			description="Lorem ipsum dolor sit amet, consectetur adipisicing elit."
+			iconOrBrandUrl="Bell"
+		/>
+	</Preview>
+	<Snippet language="js">{allowRemoveCode}</Snippet>
+</Section>
+
+<Section
+	title="Pro Version"
+	contained={true}
+	border={true}
+	style={{ paddingRight: 0, paddingLeft: 0 }}
+>
+	<Preview wrapper={true}>
+		<Selector
+			isPro={true}
+			variation="compound"
+			title="Option 1"
+			description="Lorem ipsum dolor sit amet, consectetur adipisicing elit."
+			iconOrBrandUrl="Bell"
+		/>
+	</Preview>
+	<Snippet language="js">{proVersion}</Snippet>
+</Section>
+
+<Section
+	title="Custom Tag"
+	contained={true}
+	border={true}
+	style={{ paddingRight: 0, paddingLeft: 0 }}
+>
+	<p>Use the prop <Code small={true}>tag</Code> to add a custom text displayed in a tag</p>
+    <p>You can also use the prop <Code small={true}>tagColor</Code> to customize its color</p>
+
+    <Preview wrapper={true}>
+    	<Selector
+            tag="New"
+    		tagColor="green"
+    		variation="compound"
+    		title="Option 1"
+    		description="Lorem ipsum dolor sit amet, consectetur adipisicing elit."
+    		iconOrBrandUrl="Bell"
+    	/>
+    </Preview>
+    <Snippet language="js">{customTagCode}</Snippet>
+
+</Section>