@app-studio/web 0.9.57 → 0.9.59

package/docs/app-studio/Events.md

@@ -0,0 +1,296 @@
+# Event Management
+
+App-Studio provides intuitive ways to manage events in your CSS through the `on` prop and underscore-prefixed properties. These features are designed to offer convenient ways to style elements based on various interactive states, represented by CSS pseudo-classes like `hover`, `active`, and `focus`.
+
+---
+
+## 1. Introduction to Event-Based Styling
+
+### Using the `on` Prop
+
+The `on` prop takes an object as its value. The keys in this object correspond to the names of the CSS pseudo-classes, and the values are objects that define the styles to apply when the event occurs.
+
+```jsx
+on={{ [eventName]: { [styleProps]: [styleValue] } }}
+```
+
+Here `eventName` is the name of the CSS pseudo-class, `styleProps` are the CSS properties you wish to change, and `styleValue` are the values you want to apply.
+
+### Using Underscore-Prefixed Properties
+
+As an alternative to the `on` prop, you can use underscore-prefixed properties directly. This provides a more concise syntax for common event-based styling:
+
+```jsx
+_hover={{ backgroundColor: 'blue.100' }}
+```
+
+You can also use string values for simple color changes:
+
+```jsx
+_hover="color.blue.500"
+```
+
+Underscore-prefixed properties support all the same events as the `on` prop, but with a more direct syntax. For example, instead of writing:
+
+```jsx
+on={{ hover: { backgroundColor: 'blue.100' } }}
+```
+
+You can simply write:
+
+```jsx
+_hover={{ backgroundColor: 'blue.100' }}
+```
+
+Both approaches achieve the same result, so you can choose the syntax that best fits your coding style. The underscore-prefixed approach is particularly useful when you want to apply styles to multiple different states without nesting them all within a single `on` prop object.
+
+---
+
+## 2. Usage Examples
+
+### Example 1: Changing Background Color on Hover for `View`
+
+```jsx
+<View
+  backgroundColor="grey"
+  padding={20}
+  on={{ hover: { backgroundColor: 'blue.100' } }}
+>
+  Hover over me
+</View>
+```
+
+In this example, the `View` component's background color will change to `blue.100` when the user hovers over it.
+
+### Example 2: Background Color Toggle for `Element`
+
+```jsx
+<Element backgroundColor="blue" on={{ hover: { backgroundColor: 'color.red' } }} />
+```
+
+Here, the `Element` component initially has a background color of `blue`. When hovered over, the background color toggles to `red`.
+
+---
+
+## 3. Supported Events
+
+The `on` prop supports a comprehensive set of CSS pseudo-classes, allowing you to fine-tune your UI based on various states and interactions. These are grouped by category for easier reference:
+
+### Basic Interaction States
+
+- `hover`: Triggered when the mouse is placed over the component.
+- `active`: Triggered when the component is actively being interacted with (e.g., a mouse click).
+- `focus`: Triggered when the component gains focus (e.g., through tab navigation).
+- `visited`: Triggered for links that have been visited.
+
+### Form States
+
+- `disabled`: Triggered when the component is disabled.
+- `enabled`: Triggered when the component is enabled.
+- `checked`: Triggered for checked inputs (like checkboxes or radio buttons).
+- `unchecked`: Triggered for unchecked inputs.
+- `invalid`: Triggered when a form element's value is invalid.
+- `valid`: Triggered when a form element's value is valid.
+- `required`: Triggered for form elements with the required attribute.
+- `optional`: Triggered for form elements without the required attribute.
+- `placeholder`: Triggered when an input is showing its placeholder text.
+
+### Selection States
+
+- `selected`: Triggered for selected items (like options in a select element).
+
+### Target States
+
+- `target`: Triggered when the element is the target of the URL fragment (e.g., #section).
+
+### Child Position States
+
+- `firstChild`: Triggered when the element is the first child of its parent.
+- `lastChild`: Triggered when the element is the last child of its parent.
+- `onlyChild`: Triggered when the element is the only child of its parent.
+- `firstOfType`: Triggered when the element is the first of its type among siblings.
+- `lastOfType`: Triggered when the element is the last of its type among siblings.
+
+### Other States
+
+- `empty`: Triggered when the element has no children.
+- `focusVisible`: Triggered when the element has keyboard focus.
+- `focusWithin`: Triggered when the element or any of its descendants has focus.
+
+## 4. Advanced Examples
+
+### Example 3: Form Input States Using the `on` Prop
+
+```jsx
+<Form.Input
+  value="Focus me"
+  on={{
+    focus: { borderColor: 'color.blue.500', boxShadow: '0 0 0 3px rgba(66, 153, 225, 0.5)' },
+    invalid: { borderColor: 'color.red.500' },
+    disabled: { backgroundColor: 'color.gray.100', cursor: 'not-allowed' },
+    placeholder: { color: 'color.gray.400' }
+  }}
+/>
+```
+
+This example shows how to style an input field in different states: when it has focus, when it contains invalid data, when it's disabled, and when it's showing placeholder text.
+
+### Example 3b: Form Input States Using Underscore Properties
+
+```jsx
+<Form.Input
+  value="Focus me"
+  _focus={{ borderColor: 'color.blue.500', boxShadow: '0 0 0 3px rgba(66, 153, 225, 0.5)' }}
+  _invalid={{ borderColor: 'color.red.500' }}
+  _disabled={{ backgroundColor: 'color.gray.100', cursor: 'not-allowed' }}
+  _placeholder={{ color: 'color.gray.400' }}
+/>
+```
+
+This example achieves the same result as the previous one but uses the more concise underscore-prefixed properties.
+
+### Example 4: Interactive Button with Multiple States Using the `on` Prop
+
+```jsx
+<Button
+  backgroundColor="color.blue.500"
+  color="white"
+  padding={10}
+  borderRadius={4}
+  on={{
+    hover: { backgroundColor: 'color.blue.600', shadow: 3 },
+    active: { backgroundColor: 'color.blue.700', transform: 'scale(0.98)', shadow: 1 },
+    focus: { boxShadow: '0 0 0 3px rgba(66, 153, 225, 0.5)' },
+    disabled: { opacity: 0.6, cursor: 'not-allowed', shadow: 0 }
+  }}
+>
+  Click Me
+</Button>
+```
+
+> **Note:** You can use the `shadow` property inside the `on` prop to change the shadow level based on interaction state. The shadow property accepts numbers from 0-9, with higher numbers creating more pronounced shadows.
+
+This button changes its appearance based on different interaction states, providing visual feedback to users.
+
+### Example 4b: Interactive Button with Multiple States Using Underscore Properties
+
+```jsx
+<Button
+  backgroundColor="color.blue.500"
+  color="white"
+  padding={10}
+  borderRadius={4}
+  _hover={{ backgroundColor: 'color.blue.600', shadow: 3 }}
+  _active={{ backgroundColor: 'color.blue.700', transform: 'scale(0.98)', shadow: 1 }}
+  _focus={{ boxShadow: '0 0 0 3px rgba(66, 153, 225, 0.5)' }}
+  _disabled={{ opacity: 0.6, cursor: 'not-allowed', shadow: 0 }}
+>
+  Click Me
+</Button>
+```
+
+This example achieves the same result as the previous one but uses the more concise underscore-prefixed properties.
+
+### Example 5: List Item with Position-Based Styling
+
+```jsx
+<View as="ul" padding={0} margin={0} listStyle="none">
+  {items.map(item => (
+    <View
+      as="li"
+      padding={10}
+      borderBottom="1px solid color.gray.200"
+      on={{
+        firstChild: { borderTop: '1px solid color.gray.200' },
+        lastChild: { borderBottom: 'none' },
+        hover: { backgroundColor: 'color.gray.50' }
+      }}
+    >
+      {item.name}
+    </View>
+  ))}
+</View>
+```
+
+This example shows how to apply different styles to list items based on their position in the list.
+
+### Example 6: Form Checkbox with State Styling
+
+```jsx
+<View
+  as="label"
+  display="flex"
+  alignItems="center"
+  cursor="pointer"
+>
+  <Input
+    type="checkbox"
+    marginRight={8}
+    on={{
+      checked: { /* Custom styles for the checked state */ },
+      focus: { outline: 'none', boxShadow: '0 0 0 2px color.blue.300' }
+    }}
+  />
+  Accept terms and conditions
+</View>
+```
+
+This example demonstrates styling a checkbox input based on its checked and focus states.
+
+---
+
+## 5. Combining with Animations
+
+### Using the `on` Prop with Animations
+
+The `on` prop can be combined with animations to create dynamic effects:
+
+```jsx
+<Button
+  padding={10}
+  backgroundColor="color.purple.500"
+  color="white"
+  borderRadius={4}
+  on={{
+    hover: {
+      backgroundColor: 'color.purple.600',
+      animate: Animation.pulse({ duration: '1s', iterationCount: 'infinite' })
+    },
+    active: {
+      backgroundColor: 'color.purple.700',
+      animate: Animation.scale({ from: { transform: 'scale(1)' }, to: { transform: 'scale(0.95)' }, duration: '0.1s' })
+    }
+  }}
+>
+  Animated Button
+</Button>
+```
+
+### Using Underscore Properties with Animations
+
+You can also use underscore-prefixed properties with animations:
+
+```jsx
+<Button
+  padding={10}
+  backgroundColor="color.purple.500"
+  color="white"
+  borderRadius={4}
+  _hover={{
+    backgroundColor: 'color.purple.600',
+    animate: Animation.pulse({ duration: '1s', iterationCount: 'infinite' })
+  }}
+  _active={{
+    backgroundColor: 'color.purple.700',
+    animate: Animation.scale({ from: { transform: 'scale(1)' }, to: { transform: 'scale(0.95)' }, duration: '0.1s' })
+  }}
+>
+  Animated Button
+</Button>
+```
+
+---
+
+App-Studio provides powerful and efficient ways to manage events in your CSS through both the `on` prop and underscore-prefixed properties. These approaches offer straightforward methods for enhancing your components' interactivity, making for a more dynamic and engaging user experience.
+
+The `on` prop is great for grouping related event styles together, while underscore-prefixed properties offer a more concise syntax that some developers may prefer. By leveraging CSS pseudo-classes through either approach, you can create sophisticated UI behaviors without complex JavaScript logic.