search

Automattic / wp-calypso

The JavaScript and API powered WordPress.com
https://developer.wordpress.com
GNU General Public License v2.0
12.42k stars 1.99k forks source link

Gutenberg Component Overlap #27034

Open blowery opened 6 years ago

blowery commented 6 years ago

Gutenberg brings us the new @wordpress/components package, which contains a number of UI components that we already have analogs for in Calypso. This issue is tracking that overlap and the work we're going to adapt Gutenberg components into Calypso.

blowery commented 6 years ago

ButtonGroup

Gutenberg wraps the buttons in a div, styled as an inline-block, Calypso in a span Gutenberg passes along all props to the div, forcing the role to group (Calypso does not set the role at all) Gutenberg uses components-button-group as the base style, Calypso uses button-group Calypso forces all children to be a Button via prop-types. Calypso allows the entire group to be marked busy or primary Calypso also adds some special styles for various button types

Button

Fairly different visual style Both support (currently) passing an href to turn the button into an anchor. Gutenberg is considering dropping support for that. Both support passing through props that are not part of the prop-type spec.

Props

Gutenberg Calypso what
href href used to trigger an anchor
target n/a target for the anchor, used with href
isPrimary primary sets special classes for visual style
isLarge (default?) makes the button larger
isSmall compact makes the button smaller
isToggled n/a unsure what this does. special visual style?
isBusy busy special visual style for busy
isDefault n/a
isLink n/a used with href?
isDestructive scary used to flag destructive actions
className className used to pass along additional class names
disabled not spec'd disable the button when it's a button
n/a type what type of HTML button (button, submit, reset)
n/a target target for the anchor if href if used
n/a rel rel for the anchor if href is used
n/a borderless used a border-less button, but not a link
blowery commented 6 years ago

All of the Form* controls are quite a bit different in Gutenberg. They all compose BaseControl and have a very different DOM layout.

Copons commented 6 years ago

Let's skip the form controls for now.

ClipboardButton

Gutenberg has an additional callback that is called 4 seconds after the copy success. Both versions support passing through props that are not part of the prop-type spec.

Props

Gutenberg Calypso what
onCopy onCopy Callback on copy success.
onFinishCopy n/a 4-seconds delayed callback on copy success (e.g. to reset the label from Copied back to Copy)
text text Text to copy
icon n/a Flag that determines if using Button or IconButton
className className Additional CSS classes
Copons commented 6 years ago

DateTime

Calypso infers the 12-hour from the site settings. Gutenberg supports passing through props that are not part of the prop-type spec.

Props

Gutenberg Calypso what
currentDate selectedDay Selected date and time
onChange onDateChange On date change callback
locale n/a Localization for the date and time display (e.g. en_us)
is12Hour n/a Flag to display a 12-hour time
n/a events Used to fill the calendar
n/a posts Used to fill the calendar instead of events
n/a timezone E.g. America/Los_Angeles
n/a gmtOffset GMT offset correction
n/a displayInputChrono Flag to display something like Today at 3:53 PM
n/a onMonthChange On month change callback
n/a onDayMouseEnter react-day-picker prop
n/a onDayMouseLeave react-day-picker prop
n/a userLocale InputChrono prop
n/a site Passed through to Clock
n/a disabledDays react-day-picker prop
n/a showOutsideDays react-day-picker prop
n/a modifiers react-day-picker prop

DatePicker Props

Gutenberg uses react-datepicker. Calypso uses react-day-picker. Gutenberg supports passing through props that are not part of the prop-type spec.

Props

Gutenberg Calypso what
currentDate selectedDay Selected day (Moment)
onChange onSelectDay On date change callback
n/a initialMonth Date object, defaults to now (Moment) 
n/a timeReference Adjust time on day select (Moment)
n/a events Used to fill the calendar
n/a (but has props pass-thru) className Additional CSS classes
n/a onMonthChange On month change callback
n/a calendarViewDate react-day-picker prop
n/a showOutsideDays react-day-picker prop
n/a locale Used for the locale() function, a react-day-picker prop
n/a modifiers react-day-picker prop
n/a onDayMouseEnter react-day-picker prop
n/a onDayMouseLeave react-day-picker prop
n/a disabledDays react-day-picker prop

TimePicker / Clock Props

Calypso infers the 12-hour from the site settings.

Props

Gutenberg Calypso what
currentTime date Selected (date?) time
is12Hour n/a Flag to display a 12-hour time
onChange onChange On time change callback
n/a gmtOffset GMT offset correction
n/a timezone E.g. America/Los_Angeles
n/a siteId Used to get the is12hour setting
n/a siteSlug Used in the timezone section
Copons commented 6 years ago

Draggable

Both versions support passing through props that are not part of the prop-type spec.

Props

Gutenberg Calypso what
elementId n/a HTML id of the element to drag
transferData n/a Data object attached to the drag drop event
onDragStart onDrag On drag callback
onDragEnd onStop On drop callback
setTimeout n/a Used by withSafeTimeout HOC
className n/a (but has props pass-thru) Additional CSS classes
n/a width Width of the draggable element
n/a height Height of the draggable element
n/a x X position of the draggable element
n/a y Y position of the draggable element
n/a controlled Flag to let x and y control the drag position
n/a bounds Restring drag to inside the provided bound coords
Copons commented 6 years ago

DropZone

Props

Gutenberg Calypso what
onFilesDrop onFilesDrop On drop callback used when dropping a file
onHTMLDrop n/a On drop callback used when dropping an HTML content
onDrop onDrop Generic on drop callback
className className Additional CSS classes
label textLabel Custom drop message
n/a onVerifyValidTransfer Check file validity
n/a fullscreen Make the droppable area occupy the entire screen
n/a icon Custom icon for the drop message
n/a children Custom drop zone content
Copons commented 6 years ago

DropdownMenu

Gutenberg uses a controls array for the menu items. Calypso uses DropdownItem components as children. Gutenberg seems to automagically take care of the selected state; Calypso expects a custom implementation.

Props

Gutenberg Calypso what
icon icon Optional icon for the collapsed button
label n/a Label/tooltip for the collapsed button
menuLabel n/a Accessibility text for the collapsed button
controls n/a Array of menu items
n/a selectedText The selected element name in the button
n/a selectedCount If set, shows a Count in the button
n/a selectedIcon The selected element icon in the button
n/a initialSelected Initial selected item
? tabIndex tabIndex override
n/a className Additional CSS classes
n/a style Additional CSS style
n/a onSelect On select callback
n/a onToggle On toggle collapse/expand callback

control element / DropdownItem

Props

Gutenberg Calypso what
title children The item label
isDisabled disabled Disabled flag
onClick onClick On select/click callback
n/a count Optional Count
n/a compactCount Makes Count smaller
n/a icon Optional icon
n/a path Optional URL to navigate on click
n/a isDropdownOpen Checks if the dropdown is expanded
n/a selected If the item is selected

Note

Calypso also supports an options list (e.g. <SelectDropdown options={ [ ... ] } /> instead of children components, specifically for form selects, but according to the docs:

there is still more work here in order to be fully functional as a form element, not recommended use case... yet.

Gutenberg Calypso (options array) what
title label The item label
isDisabled n/a Disabled flag
onClick n/a On select/click callback
n/a value The select value
n/a isLabel If the item is a static label
n/a path Optional URL to navigate on click

Additionally, Calypso also has a DropdownLabel and a DropdownSeparator to group and separate DropdownItems.

Copons commented 6 years ago

ExternalLink

Gutenberg always adds an external icon, while in Calypso is optional. Both versions support passing through (to the a element) props that are not part of the prop-type spec.

Props

Gutenberg Calypso what
href href The link href
n/a icon Check to render an external Gridicon
n/a iconSize External icon size
n/a showIconFirst Moves the external icon before the link
n/a iconClassName External icon additional CSS classes
Copons commented 6 years ago

Modal

Gutenberg uses the withState HOC to add an isOpen internal state and a setState function. Calypso controls the modal visibility state from its parent component via the isVisible prop.

Gutenberg requires manually inserting buttons inside the modal. Calypso uses a buttons array.

Both versions are based upon react-modal, but with different layers of abstraction. It might be worthy refactoring the Calypso version to be "less abstracted" like the Gutenberg one.

Props

Gutenberg Calypso what
title n/a Modal title
onRequestClose onClose On close callback
contentLabel label aria-label for the modal content div
aria.labelledby n/a aria-labelledby for the modal content div
aria. describedby n/a aria-describedby for the modal content div
focusOnMount n/a If true, focus the first tabbable element
shouldCloseOnEsc shouldCloseOnEsc Hitting ESC will close the modal
shouldCloseOnClickOutside n/a Clicking outside will close the modal
className baseClassName (see explanation)
additionalClassNames		 Additional CSS classes
role n/a Overrides the default modal role
overlayClassName baseClassName (see explanation) Additional CSS classes for the overlay div
n/a buttons Array of buttons to add at the bottom of the modal
n/a isBackdropVisible Shows or hides the overlay
n/a isFullscreen Makes the modal full screen
n/a isVisible Controls the modal visibility state
n/a leaveTimeout Close animation speed in ms
n/a onClosed Callback called after modal closes
Copons commented 6 years ago

Notice

Props

Gutenberg Calypso what
status status The notice status: success, warning, error, or info (only Calypso)
onRemove onDismissClick On close callback
isDismissible showDismiss Shows a close action
className className Additional CSS classes
n/a icon The notice icon
n/a isLoading If the notice has an animated loading state
n/a text Optionally, Calypso can pass the notice text via props instead of as children
n/a isCompact The notice size
n/a duration If set, the notice disappears after duration ms
Copons commented 6 years ago

Popover

Gutenberg uses the withState HOC to add an isVisible internal state and a setState function. Calypso controls the modal visibility state from its parent component via the isVisible prop.

Calypso also extends this into PopoverMenu, a keyboard accessible menu inside a popover.

Props

Gutenberg Calypso what
focusOnMount n/a If true, focus the first tabbable element
position position The popover relative position; values are slightly different between the two versions
className className Additional CSS classes
onClose onClose On close callback
onClickOutside n/a On click outside callback; default behaviour in Calypso
expandOnMobile n/a Makes the popover full screen on mobile
headerTitle n/a Popover header text, shown if the popover is full screen on mobile
noArrow n/a Hides the arrow
refresh n/a Recalculates the popover size and position
n/a autoPosition Automatically calculates the popover position
n/a autoRtl Automatically adjusts the popover for RTL contexts
n/a closeOnEsc Hitting ESC will close the popover
n/a context DOM element or React ref to attach the popover to
n/a customPosition Manually positions the popover
n/a ignoreContext Prevent an element from triggering onClickOutside
n/a isVisible The popover visibility state
n/a rootClassName Additional CSS classes for the root ReactChild component inside which the popover is mounted
n/a showDelay Adds a delay to the popover opening
n/a onShow On show callback
Copons commented 6 years ago

Spinner

Gutenberg doesn't allow for any props / customizations.

Props

Gutenberg Calypso what
n/a className Additional CSS classes
n/a size The spinner size in pixels
Copons commented 6 years ago

Tooltip

Gutenberg wraps the tooltip around its anchor and automatically determines when to show and hide it. Calypso uses a React ref, and controls the tooltip visibility via an isVisible prop from the parent component.

Props

Gutenberg Calypso what
position position The tooltip relative position
children children In Gutenberg is the anchor element; in Calypso the tooltip content
text n/a The tooltip content
n/a status The style of the tooltip (error, warning, success)
n/a showOnMobile Whether to show the tooltip on mobile
n/a isVisible Whether to display the tooltip
n/a context The anchor element's ref 
mtias commented 6 years ago

Although, this is an interesting one. Should we replace Gridicons with Dashicons in Calypso?

As a first step, we should map the <Dashicon /> slug to the relevant <Gridicon /> slug and resolve dashicon to gridicon (alias it).

jasmussen commented 6 years ago

As a first step, we should map the slug to the relevant slug and resolve dashicon to gridicon (alias it).

When that happens, be sure to map size to either 24px or 18px if necessary. That's important. If Gridicons are scaled down to 20px (the Dashicons size), they'll look ugly. But if they are scaled down to 18px, then it's a .75 multiplier which will alias the pixels more nicely, and on retina screens at least will look perfect.

Material icons also have 18px versions.

And finally if, when you load the Gridicons at 18px, they aren't centered properly or something, please feel free to ping me and I'll help. Gutenberg from the start has been designed to assume icons that were bigger than Dashicons.

github-actions[bot] commented 3 years ago

This issue is stale because it has been 180 days with no activity. You can keep the issue open by adding a comment. If you do, please provide additional context and explain why you’d like it to remain open. You can also close the issue yourself — if you do, please add a brief explanation and apply one of relevant issue close labels.

github-actions[bot] commented 3 years ago

This issue is stale because it has been 180 days with no activity. You can keep the issue open by adding a comment. If you do, please provide additional context and explain why you’d like it to remain open. You can also close the issue yourself — if you do, please add a brief explanation and apply one of relevant issue close labels.