Merge pull request #667 from ditadi/headless-progress

thejackshelton · web-flow · commit 99a4e0de850b · 2024-03-26T17:52:51.000-05:00
feat: progress bar headless and styled
diff --git a/apps/website/src/_state/component-statuses.ts b/apps/website/src/_state/component-statuses.ts
@@ -24,6 +24,7 @@ export const statusByComponent: ComponentKitsStatuses = {
     Modal: ComponentStatus.Draft,
     Pagination: ComponentStatus.Draft,
     Popover: ComponentStatus.Draft,
+    Progress: ComponentStatus.Draft,
     RadioGroup: ComponentStatus.Draft,
     Separator: ComponentStatus.Beta,
     Skeleton: ComponentStatus.Beta,
@@ -38,6 +39,7 @@ export const statusByComponent: ComponentKitsStatuses = {
     Modal: ComponentStatus.Beta,
     Pagination: ComponentStatus.Draft,
     Popover: ComponentStatus.Beta,
+    Progress: ComponentStatus.Draft,
     Select: ComponentStatus.Beta,
     Separator: ComponentStatus.Beta,
     Tabs: ComponentStatus.Beta,
diff --git a/apps/website/src/routes/docs/headless/menu.md b/apps/website/src/routes/docs/headless/menu.md
@@ -20,6 +20,7 @@
 - [Modal](/docs/headless/modal)
 - [Pagination](/docs/headless/pagination)
 - [Popover](/docs/headless/popover)
+- [Progress](/docs/headless/progress)
 - [Select](/docs/headless/select)
 - [Separator](/docs/headless/separator)
 - [Tabs](/docs/headless/tabs)
diff --git a/apps/website/src/routes/docs/headless/progress/examples/hero.tsx b/apps/website/src/routes/docs/headless/progress/examples/hero.tsx
@@ -0,0 +1,20 @@
+import { component$, useStyles$ } from '@builder.io/qwik';
+import { Progress, ProgressIndicator } from '@qwik-ui/headless';
+import styles from '../snippets/progress.css?inline';
+
+export default component$(() => {
+  useStyles$(styles);
+
+  const progress = 30;
+
+  return (
+    <Progress value={progress} class="progress">
+      <ProgressIndicator
+        class="progress-indicator"
+        style={{
+          transform: `translateX(-${100 - progress}%)`,
+        }}
+      />
+    </Progress>
+  );
+});
diff --git a/apps/website/src/routes/docs/headless/progress/index.mdx b/apps/website/src/routes/docs/headless/progress/index.mdx
@@ -0,0 +1,88 @@
+---
+title: Qwik UI | Progress
+---
+
+import { statusByComponent } from '~/_state/component-statuses';
+import { FeatureList } from '~/components/feature-list/feature-list';
+import { Note } from '~/components/note/note';
+
+<StatusBanner status={statusByComponent.headless.Progress} />
+
+# Progress
+
+Displays a progress bar related to a task.
+
+<Showcase name="hero" />
+
+Qwik UI's Progress implementation follows the [WAI-Aria](https://www.w3.org/WAI/ARIA/apg/patterns/meter) design pattern, along with some additional API's that enhance the flexibility, types, and performance.
+
+<FeatureList
+  features={['Provides context for assistive technology to read the progress of a task.']}
+/>
+
+<div class="mb-6 flex flex-col gap-2">
+[View Source Code ↗️](https://github.com/qwikifiers/qwik-ui/tree/main/packages/kit-headless/src/components/progress)
+
+[Report an issue 🚨](https://github.com/qwikifiers/qwik-ui/issues)
+
+[Edit This Page 🗒️](<https://github.com/qwikifiers/qwik-ui/edit/main/apps/website/src/routes/docs/headless/(components)/progress/index.mdx>)
+
+</div>
+
+## Building blocks
+
+```tsx
+import { component$ } from '@builder.io/qwik';
+import { Progress, ProgressIndicator } from '@qwik-ui/headless';
+
+export default component$(() => {
+  const progress = 30;
+
+  return (
+    <Progress value={progress} class="progress">
+      <ProgressIndicator
+        class="progress-indicator"
+        style={{
+          transform: `translateX(-${100 - progress}%)`,
+        }}
+      />
+    </Progress>
+  );
+});
+```
+
+## Accessibility
+
+Adheres to the [progressbar role requirements](https://www.w3.org/WAI/ARIA/apg/patterns/meter/).
+
+## API
+
+### Root
+
+Contains all of the progress parts.
+
+<APITable
+  propDescriptors={[
+    {
+      name: 'class',
+      type: 'string',
+      description: 'CSS classes to apply to the Progress.',
+    },
+    {
+      name: 'value',
+      type: 'number',
+      description: 'The progress value.',
+    },
+    {
+      name: 'max',
+      type: 'number',
+      description: 'The maximum progress value',
+    },
+    {
+      name: 'getValueLabel',
+      type: 'function',
+      description:
+        'A function to get the accessible label text representing the current value in a human-readable format. If not provided, the value label will be read as the numeric value as a percentage of the max value.',
+    },
+  ]}
+/>
diff --git a/apps/website/src/routes/docs/headless/progress/snippets/progress.css b/apps/website/src/routes/docs/headless/progress/snippets/progress.css
@@ -0,0 +1,13 @@
+.progress {
+  height: 1.75rem;
+  width: 100%;
+  overflow: hidden;
+  border-radius: calc(var(--border-radius) / 2);
+  background-color: hsl(var(--foreground));
+}
+
+.progress-indicator {
+  height: 100%;
+  width: 100%;
+  background-color: hsl(var(--primary));
+}
diff --git a/apps/website/src/routes/docs/styled/menu.md b/apps/website/src/routes/docs/styled/menu.md
@@ -25,6 +25,7 @@
 - [Label](/docs/styled/label)
 - [Modal](/docs/styled/modal)
 - [Popover](/docs/styled/popover)
+- [Progress](/docs/styled/progress)
 - [RadioGroup](/docs/styled/radio-group)
 - [Separator](/docs/styled/separator)
 - [Skeleton](/docs/styled/skeleton)
diff --git a/apps/website/src/routes/docs/styled/progress/examples/hero.tsx b/apps/website/src/routes/docs/styled/progress/examples/hero.tsx
@@ -0,0 +1,17 @@
+import { component$, useOnWindow, useSignal, $ } from '@builder.io/qwik';
+import { Progress } from '@qwik-ui/styled';
+
+export default component$(() => {
+  const progress = useSignal(30);
+
+  useOnWindow(
+    'load',
+    $(() => {
+      setTimeout(() => {
+        progress.value = 50;
+      }, 1000);
+    }),
+  );
+
+  return <Progress value={progress.value} />;
+});
diff --git a/apps/website/src/routes/docs/styled/progress/index.mdx b/apps/website/src/routes/docs/styled/progress/index.mdx
@@ -4,8 +4,50 @@ title: Qwik UI | Styled Progress Component
 
 import { statusByComponent } from '~/_state/component-statuses';
 
+<StatusBanner status={statusByComponent.styled.Progress} />
+
 # Progress
 
-The Qwik UI Styled progress component is your digital cheerleader, celebrating each step forward with flashy colors and a positive attitude!
+Displays an indicator showing the completion progress of a task, typically displayed as a progress bar.
 
-<StatusBanner status={statusByComponent.styled.Progress} />
+<Showcase name="hero" />
+
+## Installation
+
+### Run the following cli command or copy/paste the component code into your project
+
+```sh
+qwik-ui add progress
+```
+
+```tsx
+import { cn } from '@qwik-ui/utils';
+import {
+  Progress as QwikUIProgress,
+  ProgressIndicator as QwikUIProgressIndicator,
+} from '@qwik-ui/headless';
+import { PropsOf, component$ } from '@builder.io/qwik';
+
+export const Progress = component$<PropsOf<typeof QwikUIProgress>>((props) => {
+  return (
+    <QwikUIProgress
+      class={cn('bg-secondary relative h-4 w-full overflow-hidden rounded', props?.class)}
+    >
+      <QwikUIProgressIndicator
+        class="bg-primary h-full w-full flex-1 transition-all"
+        style={{ transform: `translateX(-${100 - (props.value || 0)}%)` }}
+      />
+    </QwikUIProgress>
+  );
+});
+```
+
+## Usage
+
+```tsx
+import { Progress } from '@qwik-ui/styled';
+```
+
+```tsx
+<Progress value={30} />
+```
diff --git a/packages/kit-headless/src/components/progress/index.ts b/packages/kit-headless/src/components/progress/index.ts
@@ -0,0 +1,2 @@
+export * from './progress-indicator';
+export * from './progress';
diff --git a/packages/kit-headless/src/components/progress/progress-context.ts b/packages/kit-headless/src/components/progress/progress-context.ts
@@ -0,0 +1,8 @@
+import { createContextId } from '@builder.io/qwik';
+
+export interface ProgressContext {
+  value: number | null;
+  max: number;
+}
+
+export const ProgressContext = createContextId<ProgressContext>('progress');
diff --git a/packages/kit-headless/src/components/progress/progress-indicator.tsx b/packages/kit-headless/src/components/progress/progress-indicator.tsx
@@ -0,0 +1,22 @@
+import { PropsOf, component$, useContext } from '@builder.io/qwik';
+import { getProgressState } from './util';
+import { ProgressContext } from './progress-context';
+
+type ProgressIndicatorElement = PropsOf<'div'>;
+export const ProgressIndicator = component$<ProgressIndicatorElement>((props) => {
+  const { ...indicatorProps } = props;
+
+  const { max, value } = useContext(ProgressContext);
+  const translateX = value ? `translateX(-${100 - value}%)` : undefined;
+
+  return (
+    <div
+      style={{ transform: translateX }}
+      title="progress_indicator"
+      data-progress={getProgressState(value, max)}
+      data-value={value ?? undefined}
+      data-max={max}
+      {...indicatorProps}
+    />
+  );
+});
diff --git a/packages/kit-headless/src/components/progress/progress.driver.ts b/packages/kit-headless/src/components/progress/progress.driver.ts
@@ -0,0 +1,28 @@
+import { type Locator, type Page } from '@playwright/test';
+export type DriverLocator = Locator | Page;
+
+export function createTestDriver<T extends DriverLocator>(rootLocator: T) {
+  const getRoot = () => {
+    return rootLocator;
+  };
+
+  const getProgressIndicator = () => {
+    return getRoot().getByTitle('progress_indicator');
+  };
+
+  const getProgressState = () => {
+    return getProgressIndicator().getAttribute('data-progress');
+  };
+
+  const getProgressValue = () => {
+    return getProgressIndicator().getAttribute('data-value');
+  };
+
+  return {
+    ...rootLocator,
+    getRoot,
+    getProgressIndicator,
+    getProgressState,
+    getProgressValue,
+  };
+}
diff --git a/packages/kit-headless/src/components/progress/progress.test.ts b/packages/kit-headless/src/components/progress/progress.test.ts
@@ -0,0 +1,36 @@
+import { expect, test, type Page } from '@playwright/test';
+import { createTestDriver } from './progress.driver';
+
+async function setup(page: Page, exampleName: string) {
+  await page.goto(`/headless/progress/${exampleName}`);
+
+  const driver = createTestDriver(page.getByRole('progressbar'));
+  const { getRoot, getProgressState, getProgressValue, getProgressIndicator } = driver;
+
+  return { driver, getRoot, getProgressState, getProgressValue, getProgressIndicator };
+}
+
+test.describe('Progress Bar usaged', () => {
+  test(`should have root and indicator`, async ({ page }) => {
+    const { driver: d } = await setup(page, 'hero');
+
+    await expect(d.getRoot()).toBeVisible();
+    await expect(d.getProgressIndicator()).toBeVisible();
+  });
+
+  test(`should have progress state loading if is not completed`, async ({ page }) => {
+    const { driver: d } = await setup(page, 'hero');
+
+    expect(d.getProgressIndicator()).toBeVisible();
+    expect(await d.getProgressState()).toBe('loading');
+    expect(await d.getProgressValue()).toBe('30');
+  });
+
+  test(`should have aria attributes`, async ({ page }) => {
+    const { driver: d } = await setup(page, 'hero');
+    await expect(d.getRoot()).toHaveAttribute('aria-valuemin', '0');
+    await expect(d.getRoot()).toHaveAttribute('aria-valuemax', '100');
+    await expect(d.getRoot()).toHaveAttribute('aria-valuenow', '30');
+    await expect(d.getRoot()).toHaveAttribute('aria-valuetext', '30%');
+  });
+});
diff --git a/packages/kit-headless/src/components/progress/progress.tsx b/packages/kit-headless/src/components/progress/progress.tsx
@@ -1,11 +1,57 @@
-import { ProgressHTMLAttributes, PropsOf } from '@builder.io/qwik';
-import { JSX } from '@builder.io/qwik/jsx-runtime';
-export type { ProgressHTMLAttributes } from '@builder.io/qwik/core';
+import { PropsOf, Slot, component$, useContextProvider } from '@builder.io/qwik';
+import {
+  defaultGetValueLabel,
+  getProgressState,
+  isNumber,
+  isValidMaxNumber,
+  isValidValueNumber,
+} from './util';
+import { ProgressContext } from './progress-context';
 
-export type ProgressProps = PropsOf<'progress'>;
+type ProgressProps = {
+  /** Maximum value of the progress bar.**/
+  max?: number;
 
-export const Progress: (
-  props: ProgressHTMLAttributes<HTMLProgressElement>,
-) => JSX.Element = (props) => {
-  return <progress {...props} />;
+  /** Current value of the progress bar. **/
+  value?: number;
+
+  /** Callback to get the label for the current value. **/
+  getValueLabel?(value: number, max: number): string;
 };
+
+type ProgressElement = PropsOf<'div'>;
+
+/** Default max value for progress bar **/
+const DEFAULT_MAX = 100;
+
+export const Progress = component$<ProgressProps & ProgressElement>((props) => {
+  const {
+    max: mapProp,
+    value: valueProp,
+    getValueLabel = defaultGetValueLabel,
+    ...progressProps
+  } = props;
+
+  const max = isValidMaxNumber(mapProp) ? mapProp : DEFAULT_MAX;
+  const value = isValidValueNumber(valueProp, max) ? valueProp : null;
+  const valueLabel = isNumber(value) ? getValueLabel(value, max) : undefined;
+
+  useContextProvider(ProgressContext, { value: value, max: max });
+
+  return (
+    <div
+      aria-valuemax={max}
+      aria-valuemin={0}
+      aria-valuenow={isNumber(value) ? value : undefined}
+      aria-valuetext={valueLabel}
+      role="progressbar"
+      title="progress-bar"
+      data-progress={getProgressState(value, max)}
+      data-value={value ?? undefined}
+      data-max={max}
+      {...progressProps}
+    >
+      <Slot />
+    </div>
+  );
+});
diff --git a/packages/kit-headless/src/components/progress/util.ts b/packages/kit-headless/src/components/progress/util.ts
diff --git a/packages/kit-headless/src/index.ts b/packages/kit-headless/src/index.ts
diff --git a/packages/kit-styled/src/components/progress/progress.tsx b/packages/kit-styled/src/components/progress/progress.tsx
diff --git a/packages/kit-styled/src/index.ts b/packages/kit-styled/src/index.ts

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+export * from './progress-indicator';`
	`2`	`+export * from './progress';`