diff --git a/packages/core/src/components/popover-canvas/popover-canvas.tsx b/packages/core/src/components/popover-canvas/popover-canvas.tsx index d16a1b666..2cb4a33bd 100644 --- a/packages/core/src/components/popover-canvas/popover-canvas.tsx +++ b/packages/core/src/components/popover-canvas/popover-canvas.tsx @@ -16,13 +16,17 @@ export class TdsPopoverCanvas { @Element() host: HTMLTdsPopoverCanvasElement; /** The CSS-selector for an element that will trigger the Popover */ - @Prop() selector: string = ''; + @Prop() selector: string; /** Element that will trigger the Popover (takes priority over selector) */ @Prop() referenceEl?: HTMLElement | null; + /** Decides if the component should be visible from the start. */ + @Prop() defaultShow: boolean = false; + /** Controls whether the Popover is shown or not. If this is set hiding and showing - * will be decided by this prop and will need to be controlled from the outside. + * will be decided by this prop and will need to be controlled from the outside. This + * also means that clicking outside of the popover won't close it. Takes precedence over `defaultShow` prop. */ @Prop() show: boolean = null; @@ -71,6 +75,7 @@ export class TdsPopoverCanvas { ref={(el) => { this.childRef = el; }} + defaultShow={this.defaultShow} >
{/* (@stencil/core@3.3.0): This div is somehow needed to keep the slotted children in a predictable order */} diff --git a/packages/core/src/components/popover-canvas/readme.md b/packages/core/src/components/popover-canvas/readme.md index 83d0d01d2..3f5563e31 100644 --- a/packages/core/src/components/popover-canvas/readme.md +++ b/packages/core/src/components/popover-canvas/readme.md @@ -27,20 +27,51 @@ use the `referenceEl` prop rather than the `selector` the referenced element can ``` +
+### Controlled vs Uncontrolled + +#### Uncontrolled mode +The popover component will be shown or hidden based on a `trigger` prop and `selector` or `referenceEl` prop. + +Example: + +```html + + +

A Popover Canvas!

+ +``` + +#### Controlled mode +The `open` prop can be used to control the visibility of the popover, meaning that the popover will be shown or hidden based on the `show` prop. Props `selector` or `referenceEl` are still needed in order to determine the position of the popover. + +Example: + +```html + + +

A Popover Canvas!

+ + +``` + +**Note:** Examples above is just for demonstration purposes, update it according to your framework syntax. + ## Properties -| Property | Attribute | Description | Type | Default | -| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | -| `modifiers` | -- | Array of modifier objects to pass to popper.js. See https://popper.js.org/docs/v2/modifiers/ | `Object[]` | `[]` | -| `offsetDistance` | `offset-distance` | Sets the offset distance | `number` | `8` | -| `offsetSkidding` | `offset-skidding` | Sets the offset skidding | `number` | `0` | -| `placement` | `placement` | Decides the placement of the Popover Canvas. See https://popper.js.org/docs/v2/constructors/#placement | `"auto" \| "auto-end" \| "auto-start" \| "bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"` | `'auto'` | -| `referenceEl` | -- | Element that will trigger the Popover (takes priority over selector) | `HTMLElement` | `undefined` | -| `selector` | `selector` | The CSS-selector for an element that will trigger the Popover | `string` | `''` | -| `show` | `show` | Controls whether the Popover is shown or not. If this is set hiding and showing will be decided by this prop and will need to be controlled from the outside. | `boolean` | `null` | +| Property | Attribute | Description | Type | Default | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | +| `defaultShow` | `default-show` | Decides if the component should be visible from the start. | `boolean` | `false` | +| `modifiers` | -- | Array of modifier objects to pass to popper.js. See https://popper.js.org/docs/v2/modifiers/ | `Object[]` | `[]` | +| `offsetDistance` | `offset-distance` | Sets the offset distance | `number` | `8` | +| `offsetSkidding` | `offset-skidding` | Sets the offset skidding | `number` | `0` | +| `placement` | `placement` | Decides the placement of the Popover Canvas. See https://popper.js.org/docs/v2/constructors/#placement | `"auto" \| "auto-end" \| "auto-start" \| "bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"` | `'auto'` | +| `referenceEl` | -- | Element that will trigger the Popover (takes priority over selector) | `HTMLElement` | `undefined` | +| `selector` | `selector` | The CSS-selector for an element that will trigger the Popover | `string` | `undefined` | +| `show` | `show` | Controls whether the Popover is shown or not. If this is set hiding and showing will be decided by this prop and will need to be controlled from the outside. This also means that clicking outside of the popover won't close it. Takes precedence over `defaultShow` prop. | `boolean` | `null` | ## Methods diff --git a/packages/core/src/components/popover-core/popover-core.tsx b/packages/core/src/components/popover-core/popover-core.tsx index a070ad0b8..3d4ee87cc 100644 --- a/packages/core/src/components/popover-core/popover-core.tsx +++ b/packages/core/src/components/popover-core/popover-core.tsx @@ -24,12 +24,18 @@ export class TdsPopoverCore { @Element() host!: HTMLTdsPopoverCoreElement; /** The CSS-selector for an element that will trigger the pop-over */ - @Prop() selector: string = ''; + @Prop() selector: string; /** Element that will trigger the pop-over (takes priority over selector) */ @Prop() referenceEl?: HTMLElement | null; - /** Decides if the Popover Menu should be visible from the start */ + /** Decides if the component should be visible from the start. */ + @Prop() defaultShow: boolean = false; + + /** Controls whether the Popover is shown or not. If this is set hiding and showing + * will be decided by this prop and will need to be controlled from the outside. This + * also means that clicking outside of the popover won't close it. Takes precedence over `defaultShow` prop. + */ @Prop() show: boolean = null; /** Decides the placement of the Popover Menu */ @@ -59,6 +65,8 @@ export class TdsPopoverCore { @State() isShown: boolean = false; + @State() disableLogic: boolean = false; + /** Property for closing popover programmatically */ @Method() async close() { this.setIsShown(false); @@ -105,11 +113,6 @@ export class TdsPopoverCore { } } - /* To enable initial loading of a component if user controls show prop*/ - componentWillLoad() { - this.setIsShown(this.show); - } - /* To observe any change of show prop after an initial load */ @Watch('show') onShowChange(newValue: boolean) { @@ -118,7 +121,9 @@ export class TdsPopoverCore { @Watch('referenceEl') onReferenceElChanged(newValue: HTMLElement, oldValue: HTMLElement) { - if (newValue !== oldValue) this.initialize({ referenceEl: newValue, trigger: this.trigger }); + if (newValue !== oldValue) { + this.initialize({ referenceEl: newValue, trigger: this.trigger }); + } } @Watch('trigger') @@ -152,7 +157,7 @@ export class TdsPopoverCore { this.setIsShown(true); }.bind(this); - private handleHide = function handleShow(event) { + private handleHide = function handleHide(event) { event.stopPropagation(); this.setIsShown(false); }.bind(this); @@ -225,15 +230,30 @@ export class TdsPopoverCore { this.popperInstance?.destroy(); } - componentDidLoad() { + connectedCallback() { + if (this.selector === undefined && this.referenceEl === undefined) { + this.disableLogic = true; + console.warn( + 'TDS-POPOVER-CORE: Popover internal logic disabled. Please provide a `selector` or `referenceEl` prop', + ); + return; + } + this.initialize({ referenceEl: this.referenceEl, trigger: this.trigger, }); } + /* To enable initial loading of a component if user controls show prop*/ + componentWillLoad() { + if (this.show === true || this.defaultShow === true) { + this.setIsShown(true); + } + } + componentDidRender() { - if (this.isShown && !this.renderedShowValue) { + if (this.isShown && !this.renderedShowValue && !this.disableLogic) { // Here we update the popper position since its position is wrong // before it is rendered. this.popperInstance.update(); diff --git a/packages/core/src/components/popover-core/readme.md b/packages/core/src/components/popover-core/readme.md index a07782336..530b966bd 100644 --- a/packages/core/src/components/popover-core/readme.md +++ b/packages/core/src/components/popover-core/readme.md @@ -1,23 +1,23 @@ # tds-core-popover - ## Properties -| Property | Attribute | Description | Type | Default | -| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | -| `autoHide` | `auto-hide` | Decides if the popover should hide automatically. Alternatevly it can be hidden externally based on emitted events. | `boolean` | `true` | -| `modifiers` | -- | Array of modifier objects to pass to popper.js. See https://popper.js.org/docs/v2/modifiers/ | `Object[]` | `[]` | -| `offsetDistance` | `offset-distance` | Sets the offset distance | `number` | `8` | -| `offsetSkidding` | `offset-skidding` | Sets the offset skidding | `number` | `0` | -| `placement` | `placement` | Decides the placement of the Popover Menu | `"auto" \| "auto-end" \| "auto-start" \| "bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"` | `'auto'` | -| `referenceEl` | -- | Element that will trigger the pop-over (takes priority over selector) | `HTMLElement` | `undefined` | -| `selector` | `selector` | The CSS-selector for an element that will trigger the pop-over | `string` | `''` | -| `show` | `show` | Decides if the Popover Menu should be visible from the start | `boolean` | `null` | -| `trigger` | `trigger` | What triggers the popover to show | `"click" \| "hover" \| "hover-popover"` | `'click'` | +| Property | Attribute | Description | Type | Default | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | +| `autoHide` | `auto-hide` | Decides if the popover should hide automatically. Alternatevly it can be hidden externally based on emitted events. | `boolean` | `true` | +| `defaultShow` | `default-show` | Decides if the component should be visible from the start. | `boolean` | `false` | +| `modifiers` | -- | Array of modifier objects to pass to popper.js. See https://popper.js.org/docs/v2/modifiers/ | `Object[]` | `[]` | +| `offsetDistance` | `offset-distance` | Sets the offset distance | `number` | `8` | +| `offsetSkidding` | `offset-skidding` | Sets the offset skidding | `number` | `0` | +| `placement` | `placement` | Decides the placement of the Popover Menu | `"auto" \| "auto-end" \| "auto-start" \| "bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"` | `'auto'` | +| `referenceEl` | -- | Element that will trigger the pop-over (takes priority over selector) | `HTMLElement` | `undefined` | +| `selector` | `selector` | The CSS-selector for an element that will trigger the pop-over | `string` | `undefined` | +| `show` | `show` | Controls whether the Popover is shown or not. If this is set hiding and showing will be decided by this prop and will need to be controlled from the outside. This also means that clicking outside of the popover won't close it. Takes precedence over `defaultShow` prop. | `boolean` | `null` | +| `trigger` | `trigger` | What triggers the popover to show | `"click" \| "hover" \| "hover-popover"` | `'click'` | ## Methods diff --git a/packages/core/src/components/popover-menu/popover-menu.tsx b/packages/core/src/components/popover-menu/popover-menu.tsx index dafdc0b52..1fe119eca 100644 --- a/packages/core/src/components/popover-menu/popover-menu.tsx +++ b/packages/core/src/components/popover-menu/popover-menu.tsx @@ -16,17 +16,20 @@ export class TdsPopoverMenu { @Element() host: HTMLTdsPopoverMenuElement; /** The CSS-selector for an element that will trigger the pop-over */ - @Prop() selector: string = ''; + @Prop() selector: string; /** Element that will trigger the pop-over (takes priority over selector) */ @Prop() referenceEl?: HTMLElement | null; /** Controls whether the Popover is shown or not. If this is set hiding and showing * will be decided by this prop and will need to be controlled from the outside. This - * also means that clicking outside of the popover won't close it. + * also means that clicking outside of the popover won't close it. Takes precedence over `defaultShow` prop. */ @Prop() show: boolean = null; + /** Decides if the component should be visible from the start. */ + @Prop() defaultShow: boolean = false; + /** Decides the placement of the Popover Menu */ @Prop() placement: Placement = 'auto'; @@ -70,6 +73,7 @@ export class TdsPopoverMenu { ref={(el) => { this.childRef = el; }} + defaultShow={this.defaultShow} >
diff --git a/packages/core/src/components/popover-menu/readme.md b/packages/core/src/components/popover-menu/readme.md index dfccf80ad..049f54aca 100644 --- a/packages/core/src/components/popover-menu/readme.md +++ b/packages/core/src/components/popover-menu/readme.md @@ -32,20 +32,53 @@ use the `referenceEl` prop rather than the `selector` the referenced element can ``` +
+### Controlled vs Uncontrolled + +#### Uncontrolled mode +The popover component will be shown or hidden based on a `trigger` prop and `selector` or `referenceEl` prop. + +Example: + +```html + + + + Action + + +``` + +#### Controlled mode +The `show` prop can be used to control the visibility of the popover, meaning that the popover will be shown or hidden based on the `show` prop. Props `selector` or `referenceEl` are still needed in order to determine the position of the popover. + +Example: + +```html + + + + Action + + + +``` + ## Properties -| Property | Attribute | Description | Type | Default | -| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | -| `fluidWidth` | `fluid-width` | If true this unsets the width (160px) of the Popover Menu | `boolean` | `false` | -| `offsetDistance` | `offset-distance` | Sets the offset distance | `number` | `8` | -| `offsetSkidding` | `offset-skidding` | Sets the offset skidding | `number` | `0` | -| `placement` | `placement` | Decides the placement of the Popover Menu | `"auto" \| "auto-end" \| "auto-start" \| "bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"` | `'auto'` | -| `referenceEl` | -- | Element that will trigger the pop-over (takes priority over selector) | `HTMLElement` | `undefined` | -| `selector` | `selector` | The CSS-selector for an element that will trigger the pop-over | `string` | `''` | -| `show` | `show` | Controls whether the Popover is shown or not. If this is set hiding and showing will be decided by this prop and will need to be controlled from the outside. This also means that clicking outside of the popover won't close it. | `boolean` | `null` | +| Property | Attribute | Description | Type | Default | +| ---------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | +| `defaultShow` | `default-show` | Decides if the component should be visible from the start. | `boolean` | `false` | +| `fluidWidth` | `fluid-width` | If true this unsets the width (160px) of the Popover Menu | `boolean` | `false` | +| `offsetDistance` | `offset-distance` | Sets the offset distance | `number` | `8` | +| `offsetSkidding` | `offset-skidding` | Sets the offset skidding | `number` | `0` | +| `placement` | `placement` | Decides the placement of the Popover Menu | `"auto" \| "auto-end" \| "auto-start" \| "bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"` | `'auto'` | +| `referenceEl` | -- | Element that will trigger the pop-over (takes priority over selector) | `HTMLElement` | `undefined` | +| `selector` | `selector` | The CSS-selector for an element that will trigger the pop-over | `string` | `undefined` | +| `show` | `show` | Controls whether the Popover is shown or not. If this is set hiding and showing will be decided by this prop and will need to be controlled from the outside. This also means that clicking outside of the popover won't close it. Takes precedence over `defaultShow` prop. | `boolean` | `null` | ## Methods diff --git a/packages/core/src/components/table/table-header-cell/readme.md b/packages/core/src/components/table/table-header-cell/readme.md index 8939f046a..0b3cce56e 100644 --- a/packages/core/src/components/table/table-header-cell/readme.md +++ b/packages/core/src/components/table/table-header-cell/readme.md @@ -21,7 +21,7 @@ | Event | Description | Type | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| `tdsSort` | Sends unique Table identifier, column key and sorting direction to the tds-table-body component, can also be listened to implement custom-sorting logic. | `CustomEvent<{ tableId: string; columnKey: string; sortingDirection: "desc" \| "asc"; }>` | +| `tdsSort` | Sends unique Table identifier, column key and sorting direction to the tds-table-body component, can also be listened to implement custom-sorting logic. | `CustomEvent<{ tableId: string; columnKey: string; sortingDirection: "asc" \| "desc"; }>` | ## Slots diff --git a/packages/core/src/components/tooltip/readme.md b/packages/core/src/components/tooltip/readme.md index 6f40efe3f..15734effc 100644 --- a/packages/core/src/components/tooltip/readme.md +++ b/packages/core/src/components/tooltip/readme.md @@ -28,6 +28,50 @@ use the `referenceEl` prop rather than the `selector` the referenced element can ``` + +
+### Controlled vs Uncontrolled + +#### Uncontrolled mode +The tooltip component will be shown or hidden based on a `trigger` prop and `selector` or `referenceEl` prop. + +Example: + +```html + + +

+ Paragraph tag inside Tooltip +

+ +``` + +#### Controlled mode +The `show` prop can be used to control the visibility of the popover, meaning that the popover will be shown or hidden based on the `show` prop. Props `selector` or `referenceEl` are still needed in order to determine the position of the popover. + +Example: + +```html + + +

+ Paragraph tag inside Tooltip +

+ + +``` + + + @@ -35,13 +79,14 @@ use the `referenceEl` prop rather than the `selector` the referenced element can | Property | Attribute | Description | Type | Default | | ------------------ | -------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | +| `defaultShow` | `default-show` | Decides if the component should be visible from the start. | `boolean` | `false` | | `mouseOverTooltip` | `mouse-over-tooltip` | Allow mouse over Tooltip. Useful when Tooltip contains clickable elements like link or button. | `boolean` | `false` | | `offsetDistance` | `offset-distance` | Sets the offset distance | `number` | `8` | | `offsetSkidding` | `offset-skidding` | Sets the offset skidding | `number` | `0` | | `placement` | `placement` | Placement of Tooltip. | `"auto" \| "auto-end" \| "auto-start" \| "bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"` | `'bottom'` | | `referenceEl` | -- | Element that will trigger the Tooltip (takes priority over selector) | `HTMLElement` | `undefined` | -| `selector` | `selector` | The CSS-selector for an element that will trigger the Tooltip | `string` | `''` | -| `show` | `show` | Prop in control of showing and hiding prop | `boolean` | `null` | +| `selector` | `selector` | The CSS-selector for an element that will trigger the Tooltip | `string` | `undefined` | +| `show` | `show` | Prop in control of showing and hiding prop. Takes precedence over `defaultOpen` prop. | `boolean` | `null` | | `text` | `text` | In case Tooltip contains only text, no HTML, a text can be passed by this prop | `string` | `''` | | `trigger` | `trigger` | What triggers the popover to show | `"click" \| "hover"` | `'hover'` | diff --git a/packages/core/src/components/tooltip/tooltip.tsx b/packages/core/src/components/tooltip/tooltip.tsx index 97911d792..f4ddfa25b 100644 --- a/packages/core/src/components/tooltip/tooltip.tsx +++ b/packages/core/src/components/tooltip/tooltip.tsx @@ -19,18 +19,21 @@ export class TdsTooltip { @Prop() text: string = ''; /** The CSS-selector for an element that will trigger the Tooltip */ - @Prop() selector: string = ''; + @Prop() selector: string; /** Element that will trigger the Tooltip (takes priority over selector) */ @Prop() referenceEl?: HTMLElement | null; + /** Decides if the component should be visible from the start. */ + @Prop() defaultShow: boolean = false; + /** Allow mouse over Tooltip. Useful when Tooltip contains clickable elements like link or button. */ @Prop() mouseOverTooltip: boolean = false; /** What triggers the popover to show */ @Prop() trigger: 'click' | 'hover' = 'hover'; - /** Prop in control of showing and hiding prop */ + /** Prop in control of showing and hiding prop. Takes precedence over `defaultOpen` prop. */ @Prop({ mutable: true }) show: boolean = null; /** Placement of Tooltip. */ @@ -105,6 +108,7 @@ export class TdsTooltip { onInternalTdsClose={() => { this.show = false; }} + defaultShow={this.defaultShow} > {this.text} {/* Slot is added to support adding HTML elements to component */}