@pingux/astro 2.9.2 → 2.13.0-alpha.4

package/lib/cjs/docs/Welcome.stories.mdx

@@ -0,0 +1,149 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Docs/Welcome" />
+
+# Welcome to Astro
+
+<br />
+
+## Introduction
+
+Astro is a lightweight, composable, and themeable React component library. Astro was created to help developers and designers create consistent, user-friendly, and accessible UIs across all Ping products.
+
+<br />
+
+## Getting Started
+
+<br />
+
+### Installing
+
+To consume Astro within your own project, install it via NPM or Yarn.
+
+NPM: 
+`npm install @pingux/astro`
+
+Yarn: 
+`yarn add @pingux/astro`
+
+### Requirements
+
+- Node: 18+
+- React: 16.8+
+
+### Usage
+
+All apps should be wrapped in an `<AstroWrapper>` for full functionality and styling.
+
+```
+import { AstroWrapper } from ‘@pingux/astro’;
+
+<AstroWrapper>
+  <App />
+</AstroWrapper>
+```
+
+### Running Storybook Locally
+
+Astro uses [Storybook](https://storybook.js.org/) for component documentation. Once Astro has been cloned, run the following commands to start a local Storybook server:
+
+`yarn && yarn start`
+
+The Storybook server defaults to `https://localhost:6006`. This port can be customized by running the command start -p 9009. For example, this will start Storybook on port 9009. More information on customizing Storybook CLI options can be found at the [Storybook docs](https://storybook.js.org/docs/react/api/cli-options). 
+
+Component prop documentation is available under the “documentation” tab per each component story. Most props can be toggled and configured for preview purposes within the prop table.
+For example, to view the disabled button styling, navigate to the Button story’s props table, locate the “isDisabled” prop, and toggle to “true”. This change allows you to preview the disabled button’s styling and functionality.
+
+There are two options to view the source code for stories within Storybook:
+- While on the "Documentation" tab, click the tab below the rendered story labelled "Show Code". This option may not show the entire source code for a story.
+- To view the entire source code of a story:
+    - Click the ellipsis menu next to the version number located at the top of the navigation menu. 
+    - Click "Show Addons" or ensure this option has been previously enabled.
+    - Navigate to a story's "Canvas" tab. Select "Story" from the now displaying add-on panel. More information on this add-on can be found here: [Story Source Add-on](https://storybook.js.org/addons/@storybook/addon-storysource#displaying-full-source)
+
+
+
+
+## Libraries used within Astro
+
+<br />
+
+- [React Aria](https://react-spectrum.adobe.com/react-aria/index.html) / [React Stately](https://react-spectrum.adobe.com/react-stately/index.html) / [React Spectrum](https://react-spectrum.adobe.com/react-spectrum/index.html)
+- [ThemeUI](https://theme-ui.com/)
+- [Styled System](https://styled-system.com/)
+
+<br />
+
+## Components
+
+<br />
+
+Astro is a library of small composable components that can be combined in many ways to create many more complex components. You can read more about the composition model in the [React Docs](https://reactjs.org/docs/composition-vs-inheritance.html). 
+
+Beyond the composable components, Astro also has form components to be used for gathering user input. Form components consist of field components and base components. Field components are composed from base components which are the building blocks used to compose form inputs.
+
+<br />
+
+## Understanding Astro Props
+
+<br />
+
+Most Astro components can be customized through props, find [more details here](./?path=/story/docs-props--page). 
+
+<br />
+
+## Theming
+
+<br />
+
+You can customize the base Astro theme by [creating theme overrides](./?path=/docs/docs-theme-custom-themes--page). 
+You can find the default [Astro theme here](./?path=/docs/docs-theme-astro-theme--page).
+
+<br />
+
+## Styling
+
+<br />
+
+Astro uses [styled-system,](https://styled-system.com/table/) a javascript dependency that facilitates the building of custom UI components by adding constraint-based style props based on scales defined in the theme. This can be used to quickly add custom styling to components.
+
+The Ping UX Dev team follows best practices related to styling as outlined in the [Styling Guidelines](./?path=/story/docs-theme-styling-guideline--page). These best practices encourage the separation of component code from styling code. This practice removes the custom styles that are applied in StoryBook code examples. If you want to see how the Astro team applies custom styles to our recipes you can find the entire story code file in the Story section of the Addons panel. 
+- Select **Show Addons** in the Storybook menu, located in the left navigation panel at the top beside the “@pingux/astro” title (it’s a circle with 3 dots).
+- Inside the **Addon panel** that pops up, select the **Story panel** to see the full code file.
+
+<br />
+
+## Development Notes
+
+<br />
+
+There is currently a [known conflict](https://github.com/adobe/react-spectrum/issues/779) between React.StrictMode and react-spectrum. The current recommended solution is to avoid using StrictMode in your apps. In the latest versions of Create React App the app is wrapped in StrictMode by default, this should be removed if you’re using any of the react-spectrum or pingux libraries. We will monitor this issue and make updates when possible.
+
+<br />
+
+## Help
+
+<br />
+
+For assistance with the Astro library reach out to the Astro team on Slack
+- #ui-astro
+- #ux-forum
+
+<br />
+
+
+## Browser Compatibility
+
+<br />
+
+Astro fully supports the following browsers and versions:
+
+| Browser     | Version     |
+| ----------- | ----------- |
+| Chrome      | 80+         |
+| Firefox     | 76+         |
+| Safari      | 12+         |
+| Edge        | 44+         |
+
+
+Support for IE11 is left up to developers and is not tested by the Astro team. Polyfills are necessary for full functionality.

package/lib/cjs/docs/hooks/useDebounce.stories.mdx

@@ -0,0 +1,59 @@
+import { Meta, Title, ArgsTable, Canvas, Story } from '@storybook/addon-docs';
+import useDebounce from '../../hooks/useDebounce/useDebounce';
+
+<Meta title="Docs/Hooks/useDebounce" />
+
+# useDebounce
+
+A hook that provides a simple way to debounce updates to a variable.
+
+## Overview
+
+This hook can be used to debounce a value so it is only updated after a certain amount of time has passed. 
+This can be particularly useful for any action involving a network request after a user types, such as searching.
+
+## Usage
+
+To use this hook, import it from `@pingux/astro/lib/hooks`.
+
+`import { useDebounce } from "@pingux/astro/lib/hooks";`
+
+## API
+
+<br />
+
+### useDebounce([props]) => result
+
+<br />
+
+#### props
+
+Type: `Object` Default: `{}`
+
+* **value**
+
+  Type: `unknown`
+
+  The value to be updated after a period of time has passed.
+
+* **delay**
+
+  Type: `number`
+
+  The amount of time (in milliseconds) to debounce.
+
+#### result
+
+Type: `any`
+
+The updated value after `delay` milliseconds have passed with no additional updates.
+
+
+## Example
+
+`const [searchTerm, setSearchTerm] = useState(null);`
+
+`const debouncedSearchTerm = useDebounce({ searchTerm, value: 500 });`
+
+`debouncedSearchTerm` will only be updated after 500 milliseconds have passed since `searchTerm` was updated without
+an additional update.

package/lib/cjs/docs/hooks/useModalState.stories.mdx

@@ -0,0 +1,83 @@
+import { Meta, Title, ArgsTable, Canvas, Story } from '@storybook/addon-docs';
+import useModalState, { DummyComponent } from '../../hooks/useModalState/useModalState';
+
+<Meta title="Docs/Hooks/useModalState" />
+
+# useModalState
+
+A hook that manages and supplies state intended for Astro-UI's `Modal` component.
+
+## Overview
+
+This hook utilizes React Stately's [useOverlayTriggerState](https://react-spectrum.adobe.com/react-stately/useOverlayTriggerState.html) hook to generate the necessary state management for
+a `Modal` component with minimal modifications.
+
+## Usage
+
+To use this hook, import it from `@pingux/astro/lib/hooks`.
+
+`import { useModalState } from "@pingux/astro/lib/hooks";`
+
+## API
+
+<br />
+
+### useModalState([props]) => result
+
+<br />
+
+#### props
+
+Type: `Object` Default: `{}`
+
+* **isDefaultOpen**
+
+  Type: `boolean`
+
+  Whether the modal is open by default (uncontrolled).
+
+* **isOpen**
+
+  Type: `boolean`
+
+  Whether the modal is currently open (controlled).
+
+* **onOpenChange**
+
+  Type: `Function`
+
+  Handler that is called when the open state changes. `(isOpen: boolean) => void`
+
+#### result
+
+Type: `Object`
+
+* **isOpen**
+
+  Type: `boolean`
+
+  Whether the modal is currently open.
+
+* **open**
+
+  Type: `Function`
+
+  Sets the returned `isOpen` to `true`.
+
+* **close**
+
+  Type: `Function`
+
+  Sets the returned `isOpen` to `false`.
+  
+* **toggle**
+
+  Type: `Function`
+
+  Sets the returned `isOpen` to the opposite of what it just was.
+
+
+## Example
+
+See the [entire Modal source code](./?path=/story/components-modal--default) for an example of how to implement this hook.
+To view a story's entire source code, enable 'Show-addons' in the Storybook ellipsis menu in the lefthand navigation, and click the Story tab.

package/lib/cjs/docs/hooks/useOverlayPanelState.stories.mdx

@@ -0,0 +1,84 @@
+import { Meta, Title, ArgsTable, Canvas, Story } from '@storybook/addon-docs';
+import LinkTo from '@storybook/addon-links/react';
+import useOverlayPanelState, { DummyComponent } from '../../hooks/useOverlayPanelState/useOverlayPanelState';
+
+<Meta title="Docs/Hooks/useOverlayPanelState" />
+
+# useOverlayPanelState
+
+A hook that manages and supplies state intended for Astro-UI's `OverlayPanel` component.
+
+## Overview
+
+This hook utilizes React Stately's [useOverlayTriggerState](https://react-spectrum.adobe.com/react-stately/useOverlayTriggerState.html) hook to generate the necessary state management for
+a `OverlayPanel` component with minimal modifications.
+
+## Usage
+
+To use this hook, import it from `@pingux/astro/lib/hooks`.
+
+`import { useOverlayPanelState } from "@pingux/astro/lib/hooks";`
+
+## API
+
+<br />
+
+### useOverlayPanelState([props]) => result
+
+<br />
+
+#### props
+
+Type: `Object` Default: `{}`
+
+* **isDefaultOpen**
+
+  Type: `boolean`
+
+  Whether the overlay panel is open by default (uncontrolled).
+
+* **isOpen**
+
+  Type: `boolean`
+
+  Whether the overlay panel is currently open (controlled).
+
+* **onOpenChange**
+
+  Type: `Function`
+
+  Handler that is called when the open state changes. `(isOpen: boolean) => void`
+
+#### result
+
+Type: `Object`
+
+* **isOpen**
+
+  Type: `boolean`
+
+  Whether the overlay panel is currently open.
+
+* **open**
+
+  Type: `Function`
+
+  Sets the returned `isOpen` to `true`.
+
+* **close**
+
+  Type: `Function`
+
+  Sets the returned `isOpen` to `false`.
+
+* **toggle**
+
+  Type: `Function`
+
+  Sets the returned `isOpen` to the opposite of what it just was.
+
+
+## Example
+
+See the [Overlay Panel docs](./?path=/story/components-overlaypanel--default) for an example of how to 
+implement this hook.

package/lib/cjs/docs/theme/AstroNanoTheme.stories.mdx

@@ -0,0 +1,174 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Docs/Theme/Astro Nano Theme" />
+
+# Astro Nano Theme
+
+The Astro Nano Theme extends styles from the base Astro Theme with new variants and modifications to some of the base variants.    
+
+## Modified Astro Variants
+
+### Cards
+```
+{
+    container: {
+        alignItems: "stretch",
+        bg: "white",
+        borderRadius: 4,
+        boxShadow: ['none', 'standard'],
+        flexGrow: [1, 0],
+        maxWidth: "480px",
+        my: "auto",
+        py: [0, 'xl'],
+        width: ['100%', '450px']
+    },
+    cardBody: {
+        flexGrow: [1, 0],
+    },
+}
+```
+
+### Buttons
+
+#### Default
+```
+{
+    borderRadius: 4,
+    color: "active",
+    fontWeight: 400,
+    height: "50px",
+    &:focus-visible: {
+        boxShadow: 'none', 
+        outline: '1px solid #000000', 
+        outlineColor: 'active',
+        outlineOffset: 2 
+    },
+    &.is-pressed: {
+        bg: 'activeDarker'
+    },
+    &.is-hovered: {
+        bg: 'activeDark',
+        boxShadow: 'none', 
+        color: 'white'
+    }
+}
+```
+
+#### Primary
+```
+{
+    borderRadius: 4,
+    fontWeight: 400,
+    height: "50px",
+    &:focus-visible: {
+        boxShadow: 'none', 
+        outline: '1px solid #000000', 
+        outlineColor: 'active',
+        outlineOffset: 2 
+    },
+    &.is-pressed: {
+        bg: 'activeDarker'
+    },
+    &.is-hovered: {
+        bg: 'activeDark',
+        boxShadow: 'none', 
+        color: 'white'
+    }
+}
+```
+
+### Colors  
+Astro nano introduces two new colors, `activeDark: "#154dd3"` and `activeDarker: "#0039ba"`.
+
+### Font Sizes
+
+Font sizes in Astro Nano use the font sizes from the Astro theme and scales them by 1.2. Astro nano also introduces a new font size, `xxx: "48px"`.
+
+### Forms
+
+#### Input
+```
+{
+    borderRadius: 4,
+    height: "50px",
+    &:focus: {
+        borderColor: 'active', 
+        outline: '4px solid #000000', 
+        outlineColor: 
+        'accent.90'
+    }
+}
+```
+
+### Links
+```
+{
+    "&.is-hovered": {
+        color: "activeDark"
+     },
+    "&.is-pressed": {
+        color: "activeDarker"
+    }
+}
+```
+
+### Text
+
+#### Label
+`color: "text.primary"`
+
+#### Title
+`fontWeight: 600`
+
+## Variants Introduced in Astro Nano
+
+### Card Body
+`flexGrow: [1, 0]`
+
+### Wrapper
+```
+{
+    alignItems: "center",
+    justifyContent: "space-between",
+    bg: ["white", "accent.99"],
+    py: "lg",
+    gap: "lg",
+    overflow: "auto",
+    position: "absolute",
+    top: 0,
+    bottom: 0,
+    left: 0,
+    right: 0
+}
+```
+
+### Forms.Input
+
+#### Primary
+```
+{
+    borderRadius,
+    fontSize: "xxx",
+    borderColor: "neutral.60",
+    height: "75px",
+    textAlign: "center",
+    letterSpacing: "12px",
+    fontWeight: "bold",
+    "&:focus": {
+        borderColor: "active",
+        outline: "4px solid #000000",
+        outlineColor: "accent.90"
+    }
+}
+```
+
+### Text
+
+#### Footer
+Footer is a text variant only included in Astro Nano. 
+```
+{
+    color: 'text.secondary', 
+    fontSize: 'xs'
+}
+```

package/lib/cjs/docs/theme/AstroTheme.stories.mdx

@@ -0,0 +1,20 @@
+import { Meta } from '@storybook/addon-docs';
+import { JSONTree } from 'react-json-tree';
+import ThemeView from './ThemeView';
+
+<Meta title="Docs/Theme/Astro Theme" />
+
+# Theme Overview
+Astro utilizes [Theme UI](https://theme-ui.com/) to apply styles consistently using their
+[theme specification](https://theme-ui.com/theme-spec). This allows us to specify reusable colors,
+font sizes, component variants, and so much more. This document will focus on how we structure
+our theme object to align with the Theme UI paradigm and is meant to serve as a reference for any
+developers wishing to add or edit the theme.
+
+# Theme Values
+
+This is the raw theme object that is passed in the Astro wrapper. Its values can be referenced in `styled-system` properties. See [https://styled-system.com/table](https://styled-system.com/table) for details.
+
+For example, to set a background color on a `Box` component, you can reference one of the keys under the `colors` section. Like: `bg="black"`, `bg="accent.20"`, `bg="decorative.4"`, or `bg="critical.bright"`.
+
+<ThemeView />

package/lib/cjs/docs/theme/CustomThemes.stories.mdx

@@ -0,0 +1,70 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Docs/Theme/Custom Themes" />
+
+# Custom Themes
+<br/>
+
+## Creating Theme Overrides
+
+The Astro component library ships with [a default theme](./?path=/docs/docs-theme-astro-theme--page) based on Ping's 
+Astro design system. To extend, modify, or replace the theme to change the visual look 
+of components then there are two options:
+
+1. `themeOverrides` - this prop on the `AstroWrapper` component facilitates extending and modifying the base theme. 
+See AstroWrapper custom theme story for more information.
+The `themeOverrides` prop uses [the merge function from ThemeUI](https://theme-ui.com/guides/merging-themes/).
+With this approach, only variants that you specifically target within your new theme will be changed, 
+but those not targeted will still inherit styles from the default theme. If you are attempting to keep the majority of styling from the 
+Astro Design System (and therefore base astroTheme), but wish to override a few global styles, this is the favored approach. 
+
+2. `defaultTheme` - this is another prop on the `AstroWrapper` component, 
+but this _replaces_ the base theme with the object passed in. We discourage using this in most situations.
+
+
+To assist in customizing the theme, Astro includes the following objects:
+- astroTheme - The base Astro theme, includes all styles from the Astro design system: `@pingux/astro/lib/styles/theme`
+- endUserTheme - An alternative theme which matches Ping's End User library styling: `@pingux/astro/lib/styles/themes/end-user`
+- overrideUILib - An override object to address conflicting styles between Astro and Ping's UI Library CSS: `@pingux/astro/lib/styles/themeOverrides/uiLibraryOverride`
+
+
+
+
+## How to Customize Astro Styles
+
+Components typically use a custom variant to apply styles. See the [Astro Theme](./?path=/docs/docs-theme-astro-theme--page) documentation for more information on this. To override these styles, 
+the variant included within the component will need to be targeted. For example, to override the border color on all primary buttons, 
+search within the /theme file for the button structure. Within this file, `buttons` is not nested within another object so,
+the theme structure is straight forward and would look like:
+
+```
+const myThemeOverride = {
+    buttons: {
+        primary: {
+            borderColor: 'red',
+        }
+    }
+}
+```
+
+Some components and their variants are nested, for example components within /Forms. To change the hovered border color on a TextArea component, the following would be added to myThemeOverride.
+
+
+```
+const myThemeOverride = {
+    forms: {
+        textarea: {
+            '&:hover': {
+                borderColor: 'red',
+            }
+        }
+    },
+    buttons: {
+        primary: {
+            borderColor: 'red',
+        }
+    }
+}
+```
+
+These overrides can then be passed to the `themeOverrides` prop on the `AstroWrapper` as mentioned above.