~whereswaldon/gio-x

ref: b0198a1b547035c76d814b60de9aec3fce6353a8 gio-x/component/README.md -rw-r--r-- 4.7 KiB
b0198a1bChris Waldon component: document and refactor tooltip types 2 months ago

#component

Go Reference

This package provides various material design components for gio.

#State

This package has no stable API, and should always be locked to a particular commit with go modules.

The included components attempt to conform to the material design specifications whenever possible, but they may not support unusual style tweaks or especially exotic configurations.

#Implemented Components

The list of currently-Implemented components follows:

The navigation drawer specified here is mostly implemented by the type NavDrawer, and the modal variant can be created with a ModalNavDrawer. The modal variant looks like this:

modal navigation drawer example screenshot

Features:

  • Animated drawer open/close.
  • Navigation items respond to hovering.
  • Navigation selection is animated.
  • Navigation item icons are optional.
  • Content can be anchored to the bottom of the drawer for pairing with a bottom app bar.

Modal features:

  • Swipe or touch scrim to close the drawer.

Known issues:

  • API targets a fairly static and simplistic menu. Sub-sections with dividers are not yet supported. An API-driven way to traverse the current menu options is also not yet supported. Contributions welcome!

#App Bar (Top and Bottom)

The App Bar specified here is mostly implemented by the type AppBar. It looks like this:

Normal state:

modal navigation drawer example screenshot

Contextual state:

modal navigation drawer example screenshot

Features:

  • Action buttons and overflow menu contents can be changed easily.
  • Overflow button disappears when no items overflow.
  • Overflow menu can be dismissed by touching the scrim outside of it.
  • Action items disapper into overflow when screen is too narrow to fit them. This is animated.
  • Navigation button icon is customizable, and the button is not drawn if no icon is provided.
  • Contextual app bar can be triggered and dismissed programatically.
  • Bar supports use as a top and bottom app bar (animates the overflow menu in the proper direction).

Known Issues:

  • Compact and prominent App Bars are not yet implemented.

#Side sheet (static and modal)

Side sheets (specified here) are implemented by the Sheet and ModalSheet types.

Features:

  • Animated appear/disappear

Modal features:

  • Swipe to close
  • Touch scrim to close

Known Issues:

  • Only sheets anchored on the left are currently supported (contributions welcome!)

#Text Fields

Text Fields (specified here) are implemented by the TextField type.

Features:

  • Animated label transition when selected
  • Responds to hover events
  • Exposes underlying gio editor

Known Issues:

  • Icons, hint text, error text, prefix/suffix, and other features are not yet implemented.

#Dividers

The Divider type implements material dividers. You can customize the insets embedded in the type to change which kind of divider it is. Use the constructor functions to create nice defaults.

#Surfaces

The Surface type is a rounded rectangle with a background color and a drop shadow. This isn't a material component per se, but is a useful building block nonetheless.

The Menu type defines contextual menus as described here.

first menu example screenshot

Known issues:

  • Does not support nested submenus (yet).

The MenuItem type provides widgets suitable for use within the Menu, though any widget can be used. Here are some MenuItems in action:

second menu example screenshot

#ContextArea

The ContextArea type is a helper type that defines an area that accepts right-clicks. This area will display a widget when clicked (anchored at the click position). The displayed widget is overlaid on other content, and is therefore useful in displaying contextual menus.

Known issues:

  • the heuristic that ContextArea uses to attempt to avoid off-screen drawing of its contextual content can fail or backfire. Suggestions for improving this are welcome.