Skip to content

Commit

Permalink
docs(dropdown): complete dropdown docs
Browse files Browse the repository at this point in the history 
fixes: #19
  • Loading branch information
@Sukaato
Sukaato committed Aug 27, 2024
1 parent 1ab042a commit a428db0
Show file tree
Hide file tree
Showing 8 changed files with 78 additions and 36 deletions.
4 changes: 2 additions & 2 deletions .github/workflows/actions/quality/action.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ runs:
run: npm install -w @poppy-ui/${{ inputs.package }} @poppy-ui/core @poppy-ui/docs
shell: bash

- name: Format
- name: Format
run: npx @biomejs/biome format --reporter github
working-directory: ./packages/${{ inputs.package }}
shell: bash
Expand All @@ -38,7 +38,7 @@ runs:
shell: bash

- name: Test
run: npm run test:spec --passWithNoTests --coverage
run: npm run test:spec -- --passWithNoTests --coverage
working-directory: ./packages/${{ inputs.package }}
shell: bash

Expand Down
1 change: 0 additions & 1 deletion packages/core/api.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,6 @@ pop-dropdown,part,backdrop
pop-dropdown,part,content
pop-dropdown,part,dropdown
pop-dropdown,part,trigger
pop-dropdown,part,{name}

pop-img,shadow
pop-img,prop,alt,string,undefined,false,false
Expand Down
4 changes: 2 additions & 2 deletions packages/core/playwright.config.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,8 +86,8 @@ const config: PlaywrightTestConfig = {
/* Configure projects for major browsers */
projects,
webServer: {
command: 'serve -p 3333',
port: 3333,
command: 'npm start -- --config stencil.test.config.ts',
port: 2222,
reuseExistingServer: !process.env.CI
}
};
Expand Down
11 changes: 9 additions & 2 deletions packages/core/src/components-config.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -190,11 +190,18 @@ export namespace Configuration {
open?: boolean;
};
'pop-dropdown'?: {
/**
* Describe where the content is displayed relatively to the trigger
* - `"left"`: Open on left
* - `"right"`: Open on right
* - `"top"`: Open on top
* - `"bottom"`: Open on bottom
*/
side?: DropdownSide;
/**
* Describes how the dropdown has to be alined
* - "start": Align to the left in LTR and to the right in RTL.
* - "end": Align to the right in LTR and to the left in RTL.
* - `"start"`: Align to the left in LTR and to the right in RTL.
* - `"end"`: Align to the right in LTR and to the left in RTL.
*/
align?: DropdownAlign;
/**
Expand Down
22 changes: 16 additions & 6 deletions packages/core/src/components.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -341,11 +341,11 @@ export namespace Components {
"triggerAction"?: TriggerAction;
}
/**
* Describe whats does the component
* Dropdown can open a menu or any other element when the button is clicked.
*/
interface PopDropdown {
/**
* Describes how the dropdown has to be alined - "start": Align to the left in LTR and to the right in RTL. - "end": Align to the right in LTR and to the left in RTL.
* Describes how the dropdown has to be alined - `"start"`: Align to the left in LTR and to the right in RTL. - `"end"`: Align to the right in LTR and to the left in RTL.
* @config
* @default "start"
*/
Expand All @@ -356,13 +356,21 @@ export namespace Components {
* @default 100
*/
"debounce"?: number;
/**
* Close the dropdown.
* @returns return `true` if the dropdown has been closed, otherwise `false`.
*/
"dismiss": () => Promise<boolean>;
/**
* Force the dropdown to be shown
* @config
* @default false
*/
"open"?: boolean;
/**
* Open the dropdown.
* @returns return `true` if the dropdown has been opened, otherwise `false`.
*/
"present": () => Promise<boolean>;
/**
* If `true`, a backdrop will be displayed behind the modal. This property controls whether or not the backdrop darkens the screen when the modal is presented.
Expand All @@ -371,6 +379,7 @@ export namespace Components {
*/
"showBackdrop"?: boolean;
/**
* Describe where the content is displayed relatively to the trigger - `"left"`: Open on left - `"right"`: Open on right - `"top"`: Open on top - `"bottom"`: Open on bottom
* @config
* @default "bottom"
*/
Expand Down Expand Up @@ -1556,7 +1565,7 @@ declare global {
"didDismiss": void;
}
/**
* Describe whats does the component
* Dropdown can open a menu or any other element when the button is clicked.
*/
interface HTMLPopDropdownElement extends Components.PopDropdown, HTMLStencilElement {
addEventListener<K extends keyof HTMLPopDropdownElementEventMap>(type: K, listener: (this: HTMLPopDropdownElement, ev: PopDropdownCustomEvent<HTMLPopDropdownElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
Expand Down Expand Up @@ -2257,11 +2266,11 @@ declare namespace LocalJSX {
"triggerAction"?: TriggerAction;
}
/**
* Describe whats does the component
* Dropdown can open a menu or any other element when the button is clicked.
*/
interface PopDropdown {
/**
* Describes how the dropdown has to be alined - "start": Align to the left in LTR and to the right in RTL. - "end": Align to the right in LTR and to the left in RTL.
* Describes how the dropdown has to be alined - `"start"`: Align to the left in LTR and to the right in RTL. - `"end"`: Align to the right in LTR and to the left in RTL.
* @config
* @default "start"
*/
Expand Down Expand Up @@ -2293,6 +2302,7 @@ declare namespace LocalJSX {
*/
"showBackdrop"?: boolean;
/**
* Describe where the content is displayed relatively to the trigger - `"left"`: Open on left - `"right"`: Open on right - `"top"`: Open on top - `"bottom"`: Open on bottom
* @config
* @default "bottom"
*/
Expand Down Expand Up @@ -3456,7 +3466,7 @@ declare module "@stencil/core" {
*/
"pop-drawer": LocalJSX.PopDrawer & JSXBase.HTMLAttributes<HTMLPopDrawerElement>;
/**
* Describe whats does the component
* Dropdown can open a menu or any other element when the button is clicked.
*/
"pop-dropdown": LocalJSX.PopDropdown & JSXBase.HTMLAttributes<HTMLPopDropdownElement>;
"pop-img": LocalJSX.PopImg & JSXBase.HTMLAttributes<HTMLPopImgElement>;
Expand Down
29 changes: 23 additions & 6 deletions packages/core/src/components/dropdown/dropdown.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,14 @@ import { Show } from '../Show';
import type { DropdownAlign, DropdownSide } from './dropdown.type';

/**
* Describe whats does the component
* Dropdown can open a menu or any other element when the button is clicked.
*
* @part {name} - // Describe css part
* @part dropdown - Native `details` element
* @part trigger - Native `summary` element
* @part content - Dropdown content
* @part backdrop - Backdrop element
*
* @slot - // Describe slot content
* @slot trigger - Content that trigger the dropdown to open
*/
@Component({
tag: 'pop-dropdown',
Expand All @@ -35,7 +38,11 @@ export class Dropdown implements ComponentInterface, OverlayInterface {
@Element() host: HTMLElement & OverlayInterface;

/**
*
* Describe where the content is displayed relatively to the trigger
* - `"left"`: Open on left
* - `"right"`: Open on right
* - `"top"`: Open on top
* - `"bottom"`: Open on bottom
*
* @config
* @default "bottom"
Expand All @@ -44,8 +51,8 @@ export class Dropdown implements ComponentInterface, OverlayInterface {

/**
* Describes how the dropdown has to be alined
* - "start": Align to the left in LTR and to the right in RTL.
* - "end": Align to the right in LTR and to the left in RTL.
* - `"start"`: Align to the left in LTR and to the right in RTL.
* - `"end"`: Align to the right in LTR and to the left in RTL.
*
* @config
* @default "start"
Expand Down Expand Up @@ -118,6 +125,11 @@ export class Dropdown implements ComponentInterface, OverlayInterface {
}
}

/**
* Open the dropdown.
*
* @returns {Promise<boolean>} return `true` if the dropdown has been opened, otherwise `false`.
*/
@Method()
async present(): Promise<boolean> {
const { open } = this;
Expand All @@ -127,6 +139,11 @@ export class Dropdown implements ComponentInterface, OverlayInterface {
return true;
}

/**
* Close the dropdown.
*
* @returns {Promise<boolean>} return `true` if the dropdown has been closed, otherwise `false`.
*/
@Method()
async dismiss(): Promise<boolean> {
const { open } = this;
Expand Down
33 changes: 16 additions & 17 deletions packages/core/src/components/dropdown/readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,17 @@

## Overview

Describe whats does the component
Dropdown can open a menu or any other element when the button is clicked.

## Properties

| Property | Attribute | Description | Type | Default |
| --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------- |
| `align` | `align` | Describes how the dropdown has to be alined<br> - "start": Align to the left in LTR and to the right in RTL.<br> - "end": Align to the right in LTR and to the left in RTL. | `"end" \| "start"` | `"start"` |
| `align` | `align` | Describes how the dropdown has to be alined<br> - `"start"`: Align to the left in LTR and to the right in RTL.<br> - `"end"`: Align to the right in LTR and to the left in RTL. | `"end" \| "start"` | `"start"` |
| `debounce` | `debounce` | Set the amount of time, in milliseconds after the user no longer hover the trigger or dropdown, will dismiss.<br> Only apply on `triggerAction=hover` | `number` | `100` |
| `open` | `open` | Force the dropdown to be shown | `boolean` | `false` |
| `showBackdrop` | `show-backdrop` | If `true`, a backdrop will be displayed behind the modal.<br> This property controls whether or not the backdrop<br> darkens the screen when the modal is presented. | `boolean` | `false` |
| `side` | `side` | | `"bottom" \| "left" \| "right" \| "top"` | `"bottom"` |
| `side` | `side` | Describe where the content is displayed relatively to the trigger<br> - `"left"`: Open on left<br> - `"right"`: Open on right<br> - `"top"`: Open on top<br> - `"bottom"`: Open on bottom | `"bottom" \| "left" \| "right" \| "top"` | `"bottom"` |
| `triggerAction` | `trigger-action` | Describes what kind of intertion with the trigger (sloted element) that should cause the dropdown to open.<br> - `"click"`: the dropdown will be presented when the trigger is left clicked.<br> - `"hover"`: the dropdown will be presented when a pointer hovers over the trigger.<br> - `"context-menu"`: the dropdown will be presented when the trigger is right clicked on desktop and long pressed on mobile. This will also prevent your device's normal context menu from appearing. | `"click" \| "context-menu" \| "hover"` | `"click"` |


Expand All @@ -32,41 +32,40 @@ Describe whats does the component

### `dismiss() => Promise<boolean>`


Close the dropdown.

#### Returns

Type: `Promise<boolean>`


return `true` if the dropdown has been closed, otherwise `false`.

### `present() => Promise<boolean>`


Open the dropdown.

#### Returns

Type: `Promise<boolean>`


return `true` if the dropdown has been opened, otherwise `false`.


## Slots

| Slot | Description |
| ---- | ------------------------ |
| | // Describe slot content |
| Slot | Description |
| ----------- | ----------------------------------------- |
| `"trigger"` | Content that trigger the dropdown to open |


## Parts

| Part | Description |
| ------------ | -------------------- |
| `"backdrop"` | |
| `"content"` | |
| `"dropdown"` | |
| `"trigger"` | |
| `"{name}"` | // Describe css part |
| Part | Description |
| ------------ | ------------------------ |
| `"backdrop"` | Backdrop element |
| `"content"` | Dropdown content |
| `"dropdown"` | Native `details` element |
| `"trigger"` | Native `summary` element |


## CSS Custom Properties
Expand Down
10 changes: 10 additions & 0 deletions packages/core/stencil.test.config.ts
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
import { Config } from '@stencil/core';
import { config as base } from './stencil.config';

export const config: Config = {
...base,
devServer: {
port: 2222,
openBrowser: false,
},
};

0 comments on commit a428db0

Please sign in to comment.