Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: icon #774

Merged
merged 11 commits into from
Oct 4, 2024
Merged
Show file tree
Hide file tree
Changes from 10 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 133 additions & 0 deletions plugins/ui/docs/components/icon.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
# Icon

Custom icons can be used by wrapping them in an Icon component.
ethanalvizo marked this conversation as resolved.
Show resolved Hide resolved

## Example

```python
from deephaven import ui


@ui.component
def icons():
icon = ui.icon(name="filter")
Copy link
Contributor

@dsmmcken dsmmcken Oct 1, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

named arg is optional no? Should we be showing it as just ui.icon("filter") everywhere without the named arg or at least here.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yup it is optional it would only cause an issue if they put the icon name after another prop but I don't think that would happen often (ie. ui.icon(size="S", "bell")) so I just removed the name arg from all the examples


return icon


my_icons = icons()
```

## Available Icons

In the example provided, you can find a showcase of all available icons. Additionally, you have the ability to search for specific icons.

```python
from deephaven.ui.components.types import IconTypes
from deephaven import ui
from typing import get_args


@ui.component
def icon_search_example():
available_icons = [*get_args(IconTypes)]
filtered_icons, set_filtered_icons = ui.use_state(available_icons)

def filter_icons(search):
new_icons = []
for icon in available_icons:
if search in icon:
new_icons.append(icon)
set_filtered_icons(new_icons)

def render_icons():
entries = []

for icon in filtered_icons:
entries.append(
ui.flex(
ui.icon(name=icon),
ui.text(icon),
direction="column",
align_items="center",
)
)

return ui.grid(entries, columns=[200, 200, 200, 200], auto_rows="size-800")

return [
ui.text_field(
ui.icon("search"), on_change=filter_icons, width=800, margin_bottom=20
),
render_icons(),
]


my_icon_search_example = icon_search_example()
ethanalvizo marked this conversation as resolved.
Show resolved Hide resolved
```


## Sizing

Icons support t-shirt sizing, automatically adjusting their size when used within other components. By default, icons are sized as "M" for medium scale on desktops and "L" for large scale on mobile devices.

```python
from deephaven import ui


@ui.component
def icons():
small = ui.icon(name="bell", size="S")
default = ui.icon(name="bell")
large = ui.icon(name="bell", size="L")

return [small, default, large]


my_icons = icons()
```

## Coloring

Icons in Spectrum support four semantic colors: negative, notice, positive, and informative. While icons within React Spectrum components are usually styled with the appropriate colors, you can use the `color` prop to customize the color of standalone icons.
ethanalvizo marked this conversation as resolved.
Show resolved Hide resolved

```python
from deephaven import ui


@ui.component
def icons():
negative = ui.icon(name="bell", color="negative")
informative = ui.icon(name="bell", color="informative")
positive = ui.icon(name="bell", color="positive")

return [negative, informative, positive]


my_icons = icons()
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Create a follow up ticket. Icons should accept our theme colors rather than just these from spectrum,

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

```

## Labeling

By default, icons are treated as decorative and are hidden from assistive technology. When used within a label-less component, such as a button, an aria-label should be assigned to the parent component. If the icon is used on its own, an aria-label can be directly applied to the icon.

```python
from deephaven import ui


@ui.component
def icons():
icon_button = ui.button(ui.icon(name="squirrel"), aria_label="squirrel")
ethanalvizo marked this conversation as resolved.
Show resolved Hide resolved

return icon_button


my_icons = icons()
```


## API reference

```{eval-rst}
.. dhautofunction:: deephaven.ui.icon
```
8 changes: 8 additions & 0 deletions plugins/ui/src/deephaven/ui/components/icon.py
Original file line number Diff line number Diff line change
Expand Up @@ -112,9 +112,17 @@ def icon(
z_index: The stacking order for the element
is_hidden: Hides the element.
id: The unique identifier of the element.
aria_label: The label for the element.
aria_hidden: Whether the element is hidden from the accessibility tree.
aria_labelledby: The id of the element that labels the element.
aria_describedby: The id of the element that describes the element.
aria_details: The details for the element.
UNSAFE_class_name: Set the CSS className for the element. Only use as a last resort. Use style props instead.
UNSAFE_style: Set the inline style for the element. Only use as a last resort. Use style props instead.
key: A unique identifier used by React to render elements in a list.

Returns:
The rendered icon element.
"""

children, props = create_props(locals())
Expand Down
Loading