+{"description":"\nThe Alert component can be used to notify the user. It supports several\nvariants to provide context to the message.\n\nAlert can optionally render as a dismissible 'dialog' with a close button.\n\nThe `margin` prop can be added to give\nspace above or below the alert.\n\n```js\n---\ntype: example\n---\n<div>\n <Alert\n variant=\"success\"\n renderCloseButtonLabel=\"Close\"\n margin=\"small\"\n transition=\"none\"\n variantScreenReaderLabel=\"Success, \"\n >\n Sample success alert text. I will close w/o a transition out if you close me\n </Alert>\n <Alert\n variant=\"info\"\n renderCloseButtonLabel=\"Close\"\n margin=\"small\"\n variantScreenReaderLabel=\"Information, \"\n >\n Sample info text. I will fade out if you close me.\n </Alert>\n <Alert\n variant=\"error\"\n renderCloseButtonLabel=\"Close\"\n margin=\"small\"\n variantScreenReaderLabel=\"Error, \"\n >\n Sample error text that continues for a while\n to demonstrate what happens when the content stretches over\n several lines. It really does take a lot of prose to get the\n text to wrap when you are on a high resolution screen.\n </Alert>\n <Alert\n variant=\"warning\"\n margin=\"small\"\n variantScreenReaderLabel=\"Warning, \"\n >\n Sample warning text. This alert is not dismissible and cannot be closed.\n </Alert>\n</div>\n```\n\nThe `timeout` prop can be used to automatically dismiss an alert after a time.\n\n```js\n---\ntype: example\n---\n<Alert\n variant=\"info\"\n margin=\"small\"\n timeout={5000}\n variantScreenReaderLabel=\"Information, \"\n>\n Sample info text. I will fade out after 5 seconds\n</Alert>\n```\n\nGiven a `liveRegion` property, Alerts will guarantee a screenreader will announce their text.\nUse `liveRegionPoliteness` to choose an `aria-live` politeness setting of either `polite`\nor `assertive` (default). Use `isLiveRegionAtomic` to choose an `aria-atomic` setting\nof either `true` or `false` (default).\n\nDue to a bug in some screen readers, the live region element should be static, either through\nserver rendering or included in the static HTML file for the app. The Alert component will\nensure that element has the correct ARIA attributes.\n\nFor more information about live regions, see\n[this MDN article](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions).\n\n```js\n---\ntype: example\n---\nconst Example = () => {\n const [alerts, setAlerts] = useState([])\n const [count, setcount] = useState(0)\n\n const variants = ['info', 'success', 'warning', 'error']\n\n const addAlert = () => {\n const variant = variants[count % variants.length]\n const politeness = Math.random() < 0.5 ? 'polite' : 'assertive'\n setAlerts([\n ...alerts,\n {\n key: count,\n variant,\n politeness\n }\n ])\n setcount(count + 1)\n }\n\n const closeAlert = (key) =>\n setAlerts(alerts.filter((alert) => alert.key !== key))\n\n return (\n <div>\n <Button onClick={addAlert}>Add Alert</Button>\n {alerts.map((alert) => {\n return (\n <View key={alert.key} display=\"block\" margin=\"small 0\">\n <Alert\n variant={alert.variant}\n renderCloseButtonLabel=\"Close\"\n onDismiss={() => closeAlert(alert.key)}\n liveRegion={() => document.getElementById('flash-messages')}\n liveRegionPoliteness={alert.politeness}\n margin=\"small 0\"\n >\n This is {alert.politeness === 'polite' ? 'a' : 'an'}{' '}\n {alert.politeness} {alert.variant} alert\n </Alert>\n </View>\n )\n })}\n </div>\n )\n}\n\nrender(<Example />)\n```\n\nAlerts can be used to emit screenreader only messages too\n\n```js\n---\ntype: example\n---\nconst Example = () => {\n const [message, setMessage] = useState(null)\n const [count, setCount] = useState(1)\n\n const changeMessage = () => {\n setMessage(`this is message ${count}`)\n setCount(count + 1)\n }\n\n const clearMessage = () => {\n setMessage(null)\n setCount(count + 1)\n }\n\n return (\n <div>\n <Button onClick={changeMessage}>Change Message</Button>\n <Button onClick={clearMessage} margin=\"0 0 0 small\">\n Clear Message\n </Button>\n <Alert\n liveRegion={() => document.getElementById('flash-messages')}\n isLiveRegionAtomic\n screenReaderOnly\n >\n {message}\n </Alert>\n </div>\n )\n}\n\nrender(<Example />)\n```\n\nWhen Alerts are used inline, the shadow can be removed with the `hasShadow` property.\n\n```js\n---\ntype: example\n---\n<View as=\"div\" background=\"primary\" padding=\"large\">\n <View\n as=\"div\"\n background=\"primary\"\n padding=\"small medium\"\n borderWidth=\"small\"\n borderRadius=\"small\"\n margin=\"x-small 0\"\n >\n {lorem.paragraph()}\n </View>\n <Alert\n variant=\"info\"\n margin=\"x-small 0\"\n renderCloseButtonLabel=\"Close\"\n hasShadow={false}\n >\n This is an inline Alert, so it shouldn't have a shadow.\n </Alert>\n <View\n as=\"div\"\n background=\"primary\"\n padding=\"small medium\"\n borderWidth=\"small\"\n borderRadius=\"small\"\n margin=\"x-small 0\"\n >\n {lorem.paragraph()}\n </View>\n</View>\n```\n\n### Guidelines\n\n```js\n---\ntype: embed\n---\n<Guidelines>\n <Figure recommendation=\"yes\" title=\"Do\">\n <Figure.Item>Use the Info alert to notify the user of more information</Figure.Item>\n <Figure.Item>Use the Error alert to notify user of an error</Figure.Item>\n <Figure.Item>Use the Warning alert to notify user of a warning</Figure.Item>\n <Figure.Item>Use the Success alert to notify user of a success event or action</Figure.Item>\n <Figure.Item>Use the `variantScreenReaderLabel` prop to indicate the alert variant to screen reader users</Figure.Item>\n </Figure>\n <Figure recommendation=\"no\" title=\"Don't\">\n <Figure.Item>Have alert messaging that is more than two lines long</Figure.Item>\n <Figure.Item>Overuse alerts on the same page</Figure.Item>\n </Figure>\n</Guidelines>\n```\n\n```js\n---\ntype: embed\n---\n<Guidelines>\n <Figure recommendation=\"a11y\" title=\"Accessibility\">\n <Figure.Item>If the alert requires user interaction to be dismissed, the alert should behave as a modal dialog. Focus should be set to the alert when it appears, remain in the alert until it is dismissed, and return to a logical place on the page when the alert is dismissed</Figure.Item>\n <Figure.Item>aria-live=\"polite\" alerts will only be announced if the user is not currently doing anything. Polite should be used in most situations involving live regions that present new info to users</Figure.Item>\n <Figure.Item>aria-live=\"assertive\" alerts will be announced to the user as soon as possible, but not necessarily immediately. Assertive should be used if there is information that a user must know about right away, for example, a warning message in a form that does validation on the fly</Figure.Item>\n <Figure.Item>The aria-atomic=BOOLEAN is used to set whether or not the screen reader should always present the live region as a whole, even if only part of the region changes. The possible settings are: false or true. The default setting is false.</Figure.Item>\n </Figure>\n</Guidelines>\n```\n","displayName":"Alert","methods":[{"name":"handleRef","docblock":null,"modifiers":[],"params":[{"name":"el","optional":false,"type":{"name":"union","raw":"Element | null","elements":[{"name":"Element"},{"name":"null"}]}}],"returns":null},{"name":"handleTimeout","docblock":null,"modifiers":[],"params":[],"returns":null},{"name":"clearTimeouts","docblock":null,"modifiers":[],"params":[],"returns":null},{"name":"onExitTransition","docblock":null,"modifiers":[],"params":[],"returns":null},{"name":"close","docblock":null,"modifiers":[],"params":[],"returns":null},{"name":"isDOMNode","docblock":null,"modifiers":[],"params":[{"name":"n","optional":false,"type":{"name":"union","raw":"Element | null | undefined","elements":[{"name":"Element"},{"name":"null"},{"name":"undefined"}]}}],"returns":null},{"name":"getLiveRegion","docblock":null,"modifiers":[],"params":[],"returns":null},{"name":"initLiveRegion","docblock":null,"modifiers":[],"params":[{"name":"liveRegion","optional":false,"type":{"name":"Element","alias":"Element"}}],"returns":null},{"name":"createScreenreaderContentNode","docblock":null,"modifiers":[],"params":[],"returns":null},{"name":"createScreenreaderAlert","docblock":null,"modifiers":[],"params":[],"returns":null},{"name":"removeScreenreaderAlert","docblock":null,"modifiers":[],"params":[],"returns":null},{"name":"handleKeyUp","docblock":null,"modifiers":[],"params":[{"name":"event","optional":false,"type":{"name":"ReactKeyboardEvent","raw":"React.KeyboardEvent<ViewOwnProps>","elements":[{"name":"ViewOwnProps"}],"alias":"React.KeyboardEvent"}}],"returns":null},{"name":"renderIcon","docblock":null,"modifiers":[],"params":[],"returns":null},{"name":"renderCloseButton","docblock":null,"modifiers":[],"params":[],"returns":null},{"name":"renderAlert","docblock":null,"modifiers":[],"params":[],"returns":null},{"name":"createScreenReaderPortal","docblock":null,"modifiers":[],"params":[{"name":"liveRegion","optional":false,"type":{"name":"Element","alias":"Element"}}],"returns":null}],"props":{"children":{"required":false,"tsType":{"name":"ReactNode"},"description":"content to be rendered within Alert","defaultValue":{"value":"null","computed":false}},"variant":{"required":false,"tsType":{"name":"union","raw":"'info' | 'success' | 'warning' | 'error'","elements":[{"name":"literal","value":"'info'"},{"name":"literal","value":"'success'"},{"name":"literal","value":"'warning'"},{"name":"literal","value":"'error'"}]},"description":"Determines color and icon","defaultValue":{"value":"'info'","computed":false}},"variantScreenReaderLabel":{"required":false,"tsType":{"name":"string"},"description":"How the screen reader should announce the alert variant. While the `variant` prop sets the color and icon for the alert component, this label should be a textual representation of that information. So e.g. if the variant is `info`, this label could be \"Information,\" or \"Information alert,\". Note the `,` at the end of the label which helps the screenreader to be more natural sounding."},"liveRegion":{"required":false,"tsType":{"name":"union","raw":"Element | null | (() => Element | null | undefined)","elements":[{"name":"Element"},{"name":"null"},{"name":"unknown"}]},"description":"A DOM element or function that returns an element where screenreader alerts will be placed."},"liveRegionPoliteness":{"required":false,"tsType":{"name":"union","raw":"'polite' | 'assertive'","elements":[{"name":"literal","value":"'polite'"},{"name":"literal","value":"'assertive'"}]},"description":"Choose the politeness level of screenreader alerts, sets the value of\n`aria-live`.\n\nWhen regions are specified as `polite`, assistive technologies will notify\nusers of updates but generally do not interrupt the current task,\nand updates take low priority.\n\nWhen regions are specified as `assertive`, assistive technologies will\nimmediately notify the user, and could potentially clear the speech queue\nof previous updates.","defaultValue":{"value":"'assertive'","computed":false}},"isLiveRegionAtomic":{"required":false,"tsType":{"name":"boolean"},"description":"Value for the `aria-atomic` attribute.\n`aria-atomic` controls how much is read when a change happens. Should only\nthe specific thing that changed be read or should the entire element be\nread.","defaultValue":{"value":"false","computed":false}},"screenReaderOnly":{"required":false,"tsType":{"name":"boolean"},"description":"If the alert should only be visible to screen readers","defaultValue":{"value":"false","computed":false}},"timeout":{"required":false,"tsType":{"name":"number"},"description":"Milliseconds until the Alert is dismissed automatically","defaultValue":{"value":"0","computed":false}},"margin":{"required":false,"tsType":{"name":"Spacing"},"description":"Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`,\n`small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via\nfamiliar CSS-like shorthand. For example: `margin=\"small auto large\"`.","defaultValue":{"value":"'x-small 0'","computed":false}},"renderCloseButtonLabel":{"required":false,"tsType":{"name":"Renderable"},"description":"Close button label. Can be a React component"},"onDismiss":{"required":false,"tsType":{"name":"signature","type":"function","raw":"() => void","signature":{"arguments":[],"return":{"name":"void"}}},"description":"Callback after the alert is closed"},"transition":{"required":false,"tsType":{"name":"union","raw":"'none' | 'fade'","elements":[{"name":"literal","value":"'none'"},{"name":"literal","value":"'fade'"}]},"description":"Transition used to make the alert appear and disappear","defaultValue":{"value":"'fade'","computed":false}},"open":{"required":false,"tsType":{"name":"boolean"},"description":"if open transitions from truthy to falsey, it's a signal to close and unmount the alert.\nThis is necessary to close the alert from the outside and still run the transition.","defaultValue":{"value":"true","computed":false}},"hasShadow":{"required":false,"tsType":{"name":"boolean"},"description":"If the alert should have a shadow.","defaultValue":{"value":"true","computed":false}},"renderCustomIcon":{"required":false,"tsType":{"name":"Renderable"},"description":"An icon, or function that returns an icon. Setting it will override the variant's icon."}},"category":"components","relativePath":"packages/ui-alerts/src/Alert/v1/index.tsx","extension":".tsx","srcPath":"packages/ui-alerts/src/Alert/v1/index.tsx","srcUrl":"https://github.com/instructure/instructure-ui/tree/master/packages/ui-alerts/src/Alert/v1/index.tsx","packageName":"@instructure/ui-alerts","requirePath":"@instructure/ui-alerts/lib/Alert/v1/index","requireStr":"require('/home/runner/work/instructure-ui/instructure-ui/packages/ui-alerts/src/Alert/v1/index.tsx').default","esPath":"@instructure/ui-alerts/es/Alert/v1/index","themePath":"packages/ui-alerts/src/Alert/v1/styles.ts","themeUrl":"https://github.com/instructure/instructure-ui/tree/master/packages/ui-alerts/src/Alert/v1/styles.ts","id":"Alert","title":"Alert","componentVersion":"v1","componentDirName":"Alert"}
0 commit comments