diff --git a/src/components/ItemProvider/ItemProvider.stories.mdx b/src/components/ItemProvider/ItemProvider.stories.mdx index fcd42ef..cc9d906 100644 --- a/src/components/ItemProvider/ItemProvider.stories.mdx +++ b/src/components/ItemProvider/ItemProvider.stories.mdx @@ -1,17 +1,88 @@ -import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks'; +import { Meta, Story, Canvas, ArgsTable } from '@storybook/addon-docs/blocks'; +import ItemProvider from "./ItemProvider"; -Utility component that uses [React Contexts](https://reactjs.org/docs/context.html) [React Stateful Variables](https://reactjs.org/docs/hooks-state.html) to provide global access to the active item object. + -Two functions are exported: +# Overview -Function | Descrioption -- | - -`useItem` | Returns a reference to the state variable holding the current Item. Defaults to `false`. -`useItemSetter` | Returns a reference to the state variable update function. +A [context provider](https://reactjs.org/docs/context.html) exposing hooks to access and set the active Item. + +## Basic Usage +To use ItemProvider, wrap children elements inside it: +```js +import AuthProvider from "./AuthProvider"; + +export default function App(){ + return ( + + + + ); +} +``` + +## Hooks + +| Name | Descrioption | Type | +| - | - | - | +| `useItem` | Returns a reference to the current active Item. Defaults to an empty object. | `Object` | +| `useItemSetter` | Returns a callback to set the active Item. | `function` | For an in depth explanation of this pattern, see [this GitHub comment](https://github.itap.purdue.edu/ECN/webqueue2/issues/15#issuecomment-341). +## Examples +### Use Item +```js +// DisplayItemStatus +import { useItem } from "./ItemProvider"; + +export default function DisplayItemStatus(){ + const item = useItem(); + return ( + item + ? `${item.queue} ${item.number}: ${item.status} + : "No item is active." + ); +} +``` +```js +// App.js +import ItemProviders from "./ItemProvider"; +import DisplayItemStatus from "./DisplayItemStatus"; + +export default function App(){ + return ( + + + + ); +} +``` + +### Set Item +```js +// UpdateItemButton +import { useItemSetter } from "./ItemProvider"; - +export default function UpdateItemButton(){ + const item = {"queue": "ce", "number": 100, "lastUpdated": "2020-12-01T19:53:00-0500", "headers": [{"type": "Merged-Time", "content": "2020-06-23T13:31:53-0400"}, {"type": "Merged-By", "content": "campb303"}, {"type": "QTime", "content": "1"}, {"type": "QTime-Updated-Time", "content": "2020-06-23T13:28:50-0400"}, {"type": "QTime-Updated-By", "content": "campb303"}, {"type": "Time", "content": "1"}, {"type": "Time-Updated-Time", "content": "2020-06-23T13:28:50-0400"}, {"type": "Time-Updated-By", "content": "campb303"}, {"type": "Replied-Time", "content": "2020-06-23T13:28:48-0400"}, {"type": "Replied-By", "content": "campb303"}, {"type": "Edited-Time", "content": "2020-06-23T13:27:56-0400"}, {"type": "Edited-By", "content": "campb303"}, {"type": "QAssigned-To", "content": "campb303"}, {"type": "QAssigned-To-Updated-Time", "content": "2020-06-23T13:27:00-0400"}, {"type": "QAssigned-To-Updated-By", "content": "campb303"}, {"type": "Assigned-To", "content": "campb303"}, {"type": "Assigned-To-Updated-Time", "content": "2020-06-23T13:27:00-0400"}, {"type": "Assigned-To-Updated-By", "content": "campb303"}, {"type": "QStatus", "content": "Dont Delete"}, {"type": "QStatus-Updated-Time", "content": "2020-06-23T13:26:55-0400"}, {"type": "QStatus-Updated-By", "content": "campb303"}, {"type": "Status", "content": "Dont Delete"}, {"type": "Status-Updated-Time", "content": "2020-06-23T13:26:55-0400"}, {"type": "Status-Updated-By", "content": "campb303"}, {"type": "Date", "content": "2020-06-23T13:25:51-0400"}, {"type": "From", "content": "Justin Campbell "}, {"type": "Message-ID", "content": "<911CE050-3240-4980-91DD-9C3EBB8DBCF8@purdue.edu>"}, {"type": "Subject", "content": "Beepboop"}, {"type": "To", "content": "cesite@ecn.purdue.edu"}, {"type": "Content-Type", "content": "text/plain; charset=\"utf-8\""}, {"type": "X-ECN-Queue-Original-Path", "content": "/home/pier/e/queue/Attachments/inbox/2020-06-23/208-original.txt"}, {"type": "X-ECN-Queue-Original-URL", "content": "https://engineering.purdue.edu/webqueue/Attachments/inbox/2020-06-23/208-original.txt"}], "content": [{"type": "initial_message", "datetime": "2020-06-23T13:25:51-0400", "from_name": "Justin Campbell", "from_email": "campb303@purdue.edu", "to": [{"name": "", "email": "cesite@ecn.purdue.edu"}], "cc": [], "subject": "Beepboop", "content": ["Testtest\n"]}, {"type": "status", "by": "campb303", "datetime": "2020-06-23T13:26:55-0400", "content": ["Dont Delete\n"]}, {"type": "assignment", "datetime": "2020-06-23T13:27:00-0400", "by": "campb303", "to": "campb303"}, {"type": "edit", "by": "campb303", "datetime": "2020-06-23T13:27:56-0400", "content": ["This be an edit my boy\n"]}, {"type": "reply_to_user", "by": "campb303", "datetime": "2020-06-23T13:28:18-0400", "content": ["This be a reply my son\n", "\n", "Justin\n", "ECN\n"]}, {"type": "reply_from_user", "subject": "Re: Beepboop", "from_name": "Justin Campbell", "from_email": "campb303@purdue.edu", "datetime": "2020-06-23T13:30:45-0400", "content": ["Huzzah!\n"], "headers": [{"type": "Subject", "content": "Re: Beepboop\n"}, {"type": "From", "content": "Justin Campbell \n"}, {"type": "Date", "content": "Tue, 23 Jun 2020 13:30:45 -0400\n"}, {"type": "X-ECN-Queue-Original-Path", "content": "/home/pier/e/queue/Attachments/inbox/2020-06-23/212-original.txt\n"}, {"type": "X-ECN-Queue-Original-URL", "content": "https://engineering.purdue.edu/webqueue/Attachments/inbox/2020-06-23/212-original.txt\n"}]}], "isLocked": "ce 100 is locked by knewell using qvi", "userEmail": "campb303@purdue.edu", "userName": "Justin Campbell", "userAlias": "campb303", "assignedTo": "campb303", "subject": "Beepboop", "status": "Dont Delete", "priority": "", "department": "", "building": "", "dateReceived": "2020-06-23T13:25:51-0400"}; + const setItem = useItemSetter(); + return +} +``` +```js +// App.js +import ItemProviders from "./ItemProvider"; +import UpdateItemButton from "./UpdateItemButton"; -export const Template = (props) => \ No newline at end of file +export default function App(){ + return ( + + + + ); +} +``` \ No newline at end of file