From e256d3f09fd6f231c4d9e1d0f0927612a591466b Mon Sep 17 00:00:00 2001 From: Brandy Carney Date: Thu, 4 Mar 2021 12:48:52 -0500 Subject: [PATCH] feat(progress): add parts for more design customization (#22938) resolves #20062 fixes #21820 --- core/api.txt | 3 + .../components/progress-bar/progress-bar.scss | 67 ++++--- .../components/progress-bar/progress-bar.tsx | 21 ++- core/src/components/progress-bar/readme.md | 29 ++-- .../progress-bar/test/standalone/e2e.ts | 10 ++ .../progress-bar/test/standalone/index.html | 164 +++++++++++++++++- 6 files changed, 245 insertions(+), 49 deletions(-) create mode 100644 core/src/components/progress-bar/test/standalone/e2e.ts diff --git a/core/api.txt b/core/api.txt index 77c6bf1bc5..65efcba081 100644 --- a/core/api.txt +++ b/core/api.txt @@ -844,6 +844,9 @@ ion-progress-bar,prop,value,number,0,false,false ion-progress-bar,css-prop,--background ion-progress-bar,css-prop,--buffer-background ion-progress-bar,css-prop,--progress-background +ion-progress-bar,part,progress +ion-progress-bar,part,stream +ion-progress-bar,part,track ion-radio,shadow ion-radio,prop,color,string | undefined,undefined,false,false diff --git a/core/src/components/progress-bar/progress-bar.scss b/core/src/components/progress-bar/progress-bar.scss index e9904e1d23..d9bc8dfe0c 100644 --- a/core/src/components/progress-bar/progress-bar.scss +++ b/core/src/components/progress-bar/progress-bar.scss @@ -1,18 +1,19 @@ @import "../../themes/ionic.globals"; // Progress bar -// -------------------------------------------------- -// Host has no background by default - this will be added to the progress-buffer-bar +// ------------------------------------------------------------------------ +// Host has no background by default - this will be added to the progress-buffer-bar :host { /** - * @prop --background: Same as --buffer-background when using a determinate progress bar, otherwise it styles the background of the ion-progress-bar itself. - * @prop --progress-background: Color of the progress bar - * @prop --buffer-background: Color of the buffer bar - */ + * @prop --background: Background of the progress track, or the buffer bar if `buffer` is set + * @prop --progress-background: Background of the progress bar representing the current value + * @prop --buffer-background: DEPRECATED, use `--background` instead + */ --background: #{ion-color(primary, base, 0.3)}; --progress-background: #{ion-color(primary, base)}; --buffer-background: var(--background); + display: block; position: relative; @@ -25,16 +26,6 @@ overflow: hidden; } -:host(.ion-color) { - --progress-background: #{current-color(base)}; - --buffer-background: #{current-color(base, 0.3)}; -} - -// indeterminate has no progress-buffer-bar, so it will be added to the host -:host(.progress-bar-indeterminate) { - background: var(--buffer-background); -} - .progress, .progress-indeterminate, .indeterminate-bar-primary, @@ -128,27 +119,33 @@ } } -// Buffer style -// -------------------------------------------------- +// Progress Bar: Buffer Circles +// ------------------------------------------------------------------------ .buffer-circles { - background: radial-gradient(ellipse at center, var(--buffer-background) 0%, var(--buffer-background) 30%, transparent 30%) repeat-x 5px center; + background-image: radial-gradient(ellipse at center, var(--buffer-background) 0%, var(--buffer-background) 30%, transparent 30%); + + /* stylelint-disable property-blacklist */ + background-repeat: repeat-x; + background-position: 5px center; background-size: 10px 10px; + /* stylelint-enable property-blacklist */ z-index: 0; animation: buffering 450ms infinite linear; } +// Progress Bar: Reversed +// ------------------------------------------------------------------------ // If reversed is set to true, the animation will be reversed -// and the bars starting at the top right -// -------------------------------------------------- +// and the bar will start at the top right :host(.progress-bar-reversed) { transform: scaleX(-1); } -// Progress paused -// -------------------------------------------------- +// Progress Bar: Paused +// ------------------------------------------------------------------------ :host(.progress-paused) { .indeterminate-bar-secondary, @@ -158,8 +155,27 @@ } } -// Animation Keyframes -// -------------------------------------------------- +// Progress Bar: Color +// ------------------------------------------------------------------------ + +:host(.ion-color) .progress-buffer-bar { + background: #{current-color(base, 0.3)}; +} + +:host(.ion-color) .buffer-circles { + background-image: radial-gradient(ellipse at center, #{current-color(base, 0.3)} 0%, #{current-color(base, 0.3)} 30%, transparent 30%); +} + +:host(.ion-color) { + .progress, + .progress-indeterminate { + background: #{current-color(base)}; + } +} + + +// Progress Bar: Animation Keyframes +// ------------------------------------------------------------------------ // Source: https://github.com/material-components/material-components-web/blob/master/packages/mdc-linear-progress/_keyframes.scss @keyframes primary-indeterminate-translate { @@ -259,3 +275,4 @@ transform: translateX(-10px); } } + diff --git a/core/src/components/progress-bar/progress-bar.tsx b/core/src/components/progress-bar/progress-bar.tsx index 20d05d0e66..a7cd34a884 100644 --- a/core/src/components/progress-bar/progress-bar.tsx +++ b/core/src/components/progress-bar/progress-bar.tsx @@ -8,6 +8,11 @@ import { createColorClasses } from '../../utils/theme'; /** * @virtualProp {"ios" | "md"} mode - The mode determines which platform styles to use. + * + * @part progress - The progress bar that shows the current value when `type` is `"determinate"` and slides back and forth when `type` is `"indeterminate"`. + * @part stream - The animated circles that appear while buffering. This only shows when `buffer` is set and `type` is `"determinate"`. + * @part track - The track bar behind the progress bar. If the `buffer` property is set and `type` is `"determinate"` the track will be the + * width of the `buffer` value. */ @Component({ tag: 'ion-progress-bar', @@ -77,10 +82,12 @@ export class ProgressBar implements ComponentInterface { } const renderIndeterminate = () => { - return [ -
, -
- ]; + return ( +
+
+
+
+ ); }; const renderProgress = (value: number, buffer: number) => { @@ -88,7 +95,7 @@ const renderProgress = (value: number, buffer: number) => { const finalBuffer = clamp(0, buffer, 1); return [ -
, +
, /** * Buffer circles with two container to move * the circles behind the buffer progress @@ -98,9 +105,9 @@ const renderProgress = (value: number, buffer: number) => { */
-
+
, -
, +
, ]; }; diff --git a/core/src/components/progress-bar/readme.md b/core/src/components/progress-bar/readme.md index 56f88012e3..747082e1ee 100644 --- a/core/src/components/progress-bar/readme.md +++ b/core/src/components/progress-bar/readme.md @@ -1,20 +1,18 @@ # ion-progress-bar -ion-progress-bar is a horizontal progress bar to visualize the progression of an operation and activity. You can choose between two types: `determinate` and `indeterminate`. +Progress bars inform users about the status of ongoing processes, such as loading an app, submitting a form, or saving updates. There are two types of progress bars: `determinate` and `indeterminate`. ## Progress Type ### Determinate -If the percentage of an operation is known, you should use the determinate type. This is the default type and the progress is represented by the `value` property. +Determinate is the default type. It should be used when the percentage of an operation is known. The progress is represented by setting the `value` property. This can be used to show the progress increasing from 0 to 100% of the track. -A buffer shows circles as animation to indicate some activity. If the `buffer` property is smaller than 1 you can show the additional buffering progress. +If the `buffer` property is set, a buffer stream will show with animated circles to indicate activity. The value of the `buffer` property will also be represented by how much visible track there is. If the value of `buffer` is less than the `value` property, there will be no visible track. If `buffer` is equal to `1` then the buffer stream will be hidden. ### Indeterminate -If an operation is in progress and it's not necessary to indicate how long it will take. - -If you add `reversed="true"`, you receive a query which is used to indicate pre-loading. +The indeterminate type should be used when it is unknown how long the process will take. The progress bar is not tied to the `value`, instead it continually slides along the track until the process is complete. @@ -144,13 +142,22 @@ export default defineComponent({ | `value` | `value` | The value determines how much of the active bar should display when the `type` is `"determinate"`. The value should be between [0, 1]. | `number` | `0` | +## Shadow Parts + +| Part | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `"progress"` | The progress bar that shows the current value when `type` is `"determinate"` and slides back and forth when `type` is `"indeterminate"`. | +| `"stream"` | The animated circles that appear while buffering. This only shows when `buffer` is set and `type` is `"determinate"`. | +| `"track"` | The track bar behind the progress bar. If the `buffer` property is set and `type` is `"determinate"` the track will be the width of the `buffer` value. | + + ## CSS Custom Properties -| Name | Description | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `--background` | Same as --buffer-background when using a determinate progress bar, otherwise it styles the background of the ion-progress-bar itself. | -| `--buffer-background` | Color of the buffer bar | -| `--progress-background` | Color of the progress bar | +| Name | Description | +| ----------------------- | ---------------------------------------------------------------------- | +| `--background` | Background of the progress track, or the buffer bar if `buffer` is set | +| `--buffer-background` | DEPRECATED, use `--background` instead | +| `--progress-background` | Background of the progress bar representing the current value | ---------------------------------------------- diff --git a/core/src/components/progress-bar/test/standalone/e2e.ts b/core/src/components/progress-bar/test/standalone/e2e.ts new file mode 100644 index 0000000000..39cacc90dc --- /dev/null +++ b/core/src/components/progress-bar/test/standalone/e2e.ts @@ -0,0 +1,10 @@ +import { newE2EPage } from '@stencil/core/testing'; + +test('progress-bar: standalone', async () => { + const page = await newE2EPage({ + url: '/src/components/progress-bar/test/standalone?ionic:_testing=true' + }); + + const compare = await page.compareScreenshot(); + expect(compare).toMatchScreenshot(); +}); diff --git a/core/src/components/progress-bar/test/standalone/index.html b/core/src/components/progress-bar/test/standalone/index.html index 6ad1346ab4..33bae063f3 100644 --- a/core/src/components/progress-bar/test/standalone/index.html +++ b/core/src/components/progress-bar/test/standalone/index.html @@ -12,19 +12,171 @@ -

Default Progress Bar

+

Default Progress Bars

- -

Default Progress Bar with 50% width

+ + +
-

Colorize Progress Bar

+

Progress Bar: Colors

+ + + + + + -

Other types

- +
+ +

Default Types

+ + + + + + + + +
+ +

Custom: colors by part

+ + + + + + + + +
+ +

Custom: colors by css variable

+ + + + + + + + +
+ +

Custom border radius

+ + + + +

Custom transition

+ + + + + +