XY gesture support (#70)

satelllte · Asmatzaile · web-flow · commit b4ac2bf206ce · 2025-06-25T12:26:42.000+03:00
Co-authored-by: Asmatzaile &lt;gorkainventor@gmail.com&gt;
diff --git a/apps/docs/e2e/expects.ts b/apps/docs/e2e/expects.ts
@@ -112,14 +112,9 @@ export const sourceCodeLinkIsValid = async ({
   page: Page;
   filePath: string;
 }) => {
-  const url = `https://github.com/satelllte/react-knob-headless/blob/main/${filePath}`;
-  await expect(link).toHaveAttribute('href', url);
-  await link.click();
-
-  const githubPage = await page.waitForEvent('popup');
-  await expect(githubPage).toHaveURL(url);
-  await expect(githubPage).toHaveTitle(
-    `react-knob-headless/${filePath} at main · satelllte/react-knob-headless · GitHub`,
+  await expect(link).toHaveAttribute(
+    'href',
+    `https://github.com/satelllte/react-knob-headless/blob/main/${filePath}`,
   );
 };
 
diff --git a/apps/docs/e2e/index.spec.ts b/apps/docs/e2e/index.spec.ts
@@ -218,14 +218,14 @@ test.describe('"Horizontal orientation" example', () => {
     });
   });
 
-  test('has "View source" link leading to "KnobPercentageHorizontal.tsx" source code file', async ({
+  test('has "View source" link leading to "KnobPercentageX.tsx" source code file', async ({
     page,
   }) => {
     const viewSourceLink = locators.exampleViewSourceLink({container});
     await expects.sourceCodeLinkIsValid({
       link: viewSourceLink,
       page,
-      filePath: 'apps/docs/src/components/knobs/KnobPercentageHorizontal.tsx',
+      filePath: 'apps/docs/src/components/knobs/KnobPercentageX.tsx',
     });
   });
 
@@ -252,3 +252,56 @@ test.describe('"Horizontal orientation" example', () => {
     });
   });
 });
+
+test.describe('"Vertical and horizontal orientation" example', () => {
+  let container: Locator;
+
+  test.beforeEach(({page}) => {
+    container = locators.exampleContainer({
+      page,
+      name: 'Vertical and horizontal orientation',
+    });
+  });
+
+  test('has "View source" link leading to "KnobPercentageXY.tsx" source code file', async ({
+    page,
+  }) => {
+    const viewSourceLink = locators.exampleViewSourceLink({container});
+    await expects.sourceCodeLinkIsValid({
+      link: viewSourceLink,
+      page,
+      filePath: 'apps/docs/src/components/knobs/KnobPercentageXY.tsx',
+    });
+  });
+
+  test.describe('"XY" knob', () => {
+    let knob: Locator;
+    let knobOutput: Locator;
+
+    test.beforeEach(() => {
+      knob = locators.exampleKnob({container, name: 'XY'});
+      knobOutput = locators.exampleKnobOutput({container});
+    });
+
+    test('has correct default value', async () => {
+      await expects.knobValueIsEqualTo({knob, valueNow: 50});
+      await expects.knobValueTextIs({knob, knobOutput, valueText: '50%'});
+    });
+
+    test('has correct drag up behaviour', async ({page}) => {
+      await expects.knobDragsUpCorrectly({knob, valueNow: 50, page});
+    });
+
+    test('has correct drag down behaviour', async ({page}) => {
+      await expects.knobDragsDownCorrectly({knob, valueNow: 50, page});
+    });
+
+    test('has correct drag left behaviour', async ({page}) => {
+      await expects.knobDragsLeftCorrectly({knob, valueNow: 50, page});
+    });
+
+    test('has correct drag right behaviour', async ({page}) => {
+      await expects.knobDragsRightCorrectly({knob, valueNow: 50, page});
+    });
+  });
+});
diff --git a/apps/docs/e2e/locators.ts b/apps/docs/e2e/locators.ts
@@ -26,13 +26,13 @@ const decorativeKnobSky = ({page}: {page: Page}) =>
   });
 
 const exampleContainer = ({page, name}: {page: Page; name: string}) =>
-  page.getByRole('heading', {name}).locator('..');
+  page.getByRole('heading', {name, exact: true}).locator('..');
 
 const exampleViewSourceLink = ({container}: {container: Locator}) =>
   container.getByRole('link', {name: 'View source'});
 
 const exampleKnob = ({container, name}: {container: Locator; name: string}) =>
-  container.getByRole('slider', {name});
+  container.getByRole('slider', {name, exact: true});
 
 const exampleKnobOutput = ({container}: {container: Locator}) =>
   container.getByRole('status');
diff --git a/apps/docs/src/app/page.tsx b/apps/docs/src/app/page.tsx
@@ -2,7 +2,8 @@ import {GitHubLogoIcon} from '@radix-ui/react-icons';
 import {KnobDecorative} from '@/components/knobs/KnobDecorative';
 import {KnobFrequency} from '@/components/knobs/KnobFrequency';
 import {KnobPercentage} from '@/components/knobs/KnobPercentage';
-import {KnobPercentageHorizontal} from '@/components/knobs/KnobPercentageHorizontal';
+import {KnobPercentageX} from '@/components/knobs/KnobPercentageX';
+import {KnobPercentageXY} from '@/components/knobs/KnobPercentageXY';
 import {ExternalLinkUnstyled} from '@/components/ui/ExternalLinkUnstyled';
 import {TableApi} from '@/components/ui/TableApi';
 
@@ -91,9 +92,16 @@ function IndexPage() {
           <Example
             title='Horizontal orientation'
             description="The knob gesture can occur along horizontal (X) axis instead of vertical (Y) one, but it's not common in audio applications."
-            source='https://github.com/satelllte/react-knob-headless/blob/main/apps/docs/src/components/knobs/KnobPercentageHorizontal.tsx'
+            source='https://github.com/satelllte/react-knob-headless/blob/main/apps/docs/src/components/knobs/KnobPercentageX.tsx'
           >
-            <KnobPercentageHorizontal label='X' theme='stone' />
+            <KnobPercentageX label='X' theme='stone' />
+          </Example>
+          <Example
+            title='Vertical and horizontal orientation'
+            description='The knob gesture can occur along both vertical (Y) and horizontal (X) axis.'
+            source='https://github.com/satelllte/react-knob-headless/blob/main/apps/docs/src/components/knobs/KnobPercentageXY.tsx'
+          >
+            <KnobPercentageXY label='XY' theme='pink' />
           </Example>
         </div>
       </Section>
@@ -155,9 +163,17 @@ function IndexPage() {
                 name: 'orientation',
                 type: 'union',
                 defaultValue: 'vertical',
+                deprecationNotice: 'use "axis" instead.',
                 description:
                   'Orientation of the knob and its gesture. Can be "vertical" or "horizontal".',
               },
+              {
+                name: 'axis',
+                type: 'union',
+                defaultValue: 'y',
+                description:
+                  'Orientation of the knob and its gesture. Can be "x", "y", or "xy". Note, that "aria-orientation" attribute will not be set for the slider when it\'s "xy" to follow ARIA semantics.',
+              },
               {
                 name: 'includeIntoTabOrder',
                 type: 'boolean',
diff --git a/apps/docs/src/components/knobs/KnobBase.tsx b/apps/docs/src/components/knobs/KnobBase.tsx
@@ -17,7 +17,7 @@ type KnobBaseProps = Pick<
   | 'valueMax'
   | 'valueRawRoundFn'
   | 'valueRawDisplayFn'
-  | 'orientation'
+  | 'axis'
   | 'mapTo01'
   | 'mapFrom01'
 > &
@@ -36,7 +36,7 @@ export function KnobBase({
   valueMax,
   valueRawRoundFn,
   valueRawDisplayFn,
-  orientation,
+  axis,
   stepFn,
   stepLargerFn,
   mapTo01 = mapTo01Linear,
@@ -77,7 +77,7 @@ export function KnobBase({
         valueRawRoundFn={valueRawRoundFn}
         valueRawDisplayFn={valueRawDisplayFn}
         dragSensitivity={dragSensitivity}
-        orientation={orientation}
+        axis={axis}
         mapTo01={mapTo01}
         mapFrom01={mapFrom01}
         onValueRawChange={setValueRaw}
diff --git a/apps/docs/src/components/knobs/KnobFrequency.tsx b/apps/docs/src/components/knobs/KnobFrequency.tsx
@@ -3,10 +3,7 @@ import {NormalisableRange} from '@/utils/math/NormalisableRange';
 import {KnobBase} from './KnobBase';
 
 type KnobBaseProps = React.ComponentProps<typeof KnobBase>;
-type KnobFrequencyProps = Pick<
-  KnobBaseProps,
-  'theme' | 'label' | 'orientation'
->;
+type KnobFrequencyProps = Pick<KnobBaseProps, 'theme' | 'label' | 'axis'>;
 
 export function KnobFrequency(props: KnobFrequencyProps) {
   return (
diff --git a/apps/docs/src/components/knobs/KnobPercentage.tsx b/apps/docs/src/components/knobs/KnobPercentage.tsx
@@ -2,10 +2,7 @@
 import {KnobBase} from './KnobBase';
 
 type KnobBaseProps = React.ComponentProps<typeof KnobBase>;
-type KnobPercentageProps = Pick<
-  KnobBaseProps,
-  'theme' | 'label' | 'orientation'
->;
+type KnobPercentageProps = Pick<KnobBaseProps, 'theme' | 'label' | 'axis'>;
 
 export function KnobPercentage(props: KnobPercentageProps) {
   return (
diff --git a/apps/docs/src/components/knobs/KnobPercentageHorizontal.tsx b/apps/docs/src/components/knobs/KnobPercentageHorizontal.tsx
diff --git a/apps/docs/src/components/knobs/KnobPercentageX.tsx b/apps/docs/src/components/knobs/KnobPercentageX.tsx
@@ -0,0 +1,9 @@
+'use client';
+import {KnobPercentage} from './KnobPercentage';
+
+type KnobPercentageProps = React.ComponentProps<typeof KnobPercentage>;
+type KnobPercentageXProps = Omit<KnobPercentageProps, 'axis'>; // eslint-disable-line @typescript-eslint/naming-convention
+
+export function KnobPercentageX(props: KnobPercentageXProps) {
+  return <KnobPercentage axis='x' {...props} />;
+}
diff --git a/apps/docs/src/components/knobs/KnobPercentageXY.tsx b/apps/docs/src/components/knobs/KnobPercentageXY.tsx
@@ -0,0 +1,10 @@
+'use client';
+import {KnobPercentage} from './KnobPercentage';
+
+type KnobPercentageProps = React.ComponentProps<typeof KnobPercentage>;
+type KnobPercentageXYProps = Omit<KnobPercentageProps, 'axis'>; // eslint-disable-line @typescript-eslint/naming-convention
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function KnobPercentageXY(props: KnobPercentageXYProps) {
+  return <KnobPercentage axis='xy' {...props} />;
+}
diff --git a/apps/docs/src/components/ui/TableApi.tsx b/apps/docs/src/components/ui/TableApi.tsx
@@ -2,6 +2,7 @@ type Property = {
   name: string;
   type: string;
   defaultValue?: string;
+  deprecationNotice?: string;
   description: string;
 };
 
@@ -46,6 +47,11 @@ export function TableApi({properties}: TableApiProps) {
               )}
             </td>
             <td className='text-left align-baseline font-normal pb-1 md:pb-4 md:w-1/3'>
+              {property.deprecationNotice && (
+                <span className='text-red-500 block pb-1'>
+                  {'DEPRECATED: ' + property.deprecationNotice}
+                </span>
+              )}
               <span className='text-stone-300'>{property.description}</span>
             </td>
           </tr>
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/react-knob-headless/package.json b/packages/react-knob-headless/package.json
@@ -1,6 +1,6 @@
 {
   "name": "react-knob-headless",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "author": "@satelllte (https://github.com/satelllte)",
   "description": "Unstyled & accessible knob primitive for React",
diff --git a/packages/react-knob-headless/src/KnobHeadless.test.tsx b/packages/react-knob-headless/src/KnobHeadless.test.tsx
@@ -112,10 +112,74 @@ describe('KnobHeadless', () => {
     `);
   });
 
-  it('sets "aria-orientation" to "horizontal", when "orientation" is "horizontal"', () => {
+  it('sets "aria-orientation" to "horizontal", when "axis" is "x"', () => {
+    render(<KnobHeadless {...props} axis='x' aria-label='Test Knob' />);
+
+    const knob = screen.getByRole('slider', {name: 'Test Knob'});
+
+    expect(knob).toMatchInlineSnapshot(`
+      <div
+        aria-label="Test Knob"
+        aria-orientation="horizontal"
+        aria-valuemax="5"
+        aria-valuemin="-5"
+        aria-valuenow="2"
+        aria-valuetext="2 units"
+        role="slider"
+        tabindex="-1"
+      />
+    `);
+  });
+
+  it('sets no "aria-orientation", when "axis" is "xy"', () => {
+    render(<KnobHeadless {...props} axis='xy' aria-label='Test Knob' />);
+
+    const knob = screen.getByRole('slider', {name: 'Test Knob'});
+
+    expect(knob).toMatchInlineSnapshot(`
+      <div
+        aria-label="Test Knob"
+        aria-valuemax="5"
+        aria-valuemin="-5"
+        aria-valuenow="2"
+        aria-valuetext="2 units"
+        role="slider"
+        tabindex="-1"
+      />
+    `);
+  });
+
+  it('overrides "aria-orientation", when "orientation" is set on top of "axis"', () => {
+    render(
+      <KnobHeadless
+        {...props}
+        axis='x'
+        orientation='vertical'
+        aria-label='Test Knob'
+      />,
+    );
+
+    const knob = screen.getByRole('slider', {name: 'Test Knob'});
+
+    expect(knob).toMatchInlineSnapshot(`
+      <div
+        aria-label="Test Knob"
+        aria-orientation="vertical"
+        aria-valuemax="5"
+        aria-valuemin="-5"
+        aria-valuenow="2"
+        aria-valuetext="2 units"
+        role="slider"
+        tabindex="-1"
+      />
+    `);
+  });
+
+  it('overrides "aria-orientation", when "orientation" is set on top of "axis" (2)', () => {
     render(
       <KnobHeadless
         {...props}
+        axis='y'
         orientation='horizontal'
         aria-label='Test Knob'
       />,
diff --git a/packages/react-knob-headless/src/KnobHeadless.tsx b/packages/react-knob-headless/src/KnobHeadless.tsx
