feat: add Meter component

apps/www/src/content/docs/components/meter/demo.ts

@@ -0,0 +1,140 @@
+'use client';
+
+import { getPropsString } from '@/lib/utils';
+
+export const getCode = (props: any) => {
+  return `<Meter${getPropsString(props)} />`;
+};
+
+export const playground = {
+  type: 'playground',
+  controls: {
+    value: { type: 'number', initialValue: 40, min: 0, max: 100 },
+    variant: {
+      type: 'select',
+      initialValue: 'linear',
+      options: ['linear', 'circular']
+    },
+    min: { type: 'number', defaultValue: 0, min: 0, max: 99 },
+    max: { type: 'number', defaultValue: 100, min: 1, max: 100 }
+  },
+  getCode
+};
+
+export const directUsageDemo = {
+  type: 'code',
+  code: `<Flex direction="column" gap="large" style={{ width: "300px" }}>
+  <Meter value={40} />
+  <Meter value={70} />
+  <Meter value={100} />
+</Flex>`
+};
+
+export const variantDemo = {
+  type: 'code',
+  tabs: [
+    {
+      name: 'Linear',
+      code: `<Flex direction="column" gap="large" style={{ width: "300px" }}>
+  <Meter value={15}>
+    <Flex justify="between">
+      <Meter.Label>Storage used</Meter.Label>
+      <Meter.Value />
+    </Flex>
+    <Meter.Track />
+  </Meter>
+</Flex>`
+    },
+    {
+      name: 'Circular',
+      code: `<Flex gap="large" align="center">
+  <Meter variant="circular" value={70}>
+    <Meter.Track />
+    <Meter.Value />
+  </Meter>
+  <Meter variant="circular" value={30}>
+    <Meter.Track />
+    <Meter.Value />
+  </Meter>
+  <Meter variant="circular" value={90}>
+    <Meter.Track />
+    <Meter.Value />
+  </Meter>
+</Flex>`
+    }
+  ]
+};
+
+export const customizationDemo = {
+  type: 'code',
+  tabs: [
+    {
+      name: 'Linear',
+      code: `<Flex direction="column" gap="large" style={{ width: "300px" }}>
+  <Meter value={60}>
+    <Meter.Track style={{ height: 2 }} />
+  </Meter>
+  <Meter value={60}>
+    <Meter.Track />
+  </Meter>
+  <Meter value={60}>
+    <Meter.Track style={{ height: 8 }} />
+  </Meter>
+</Flex>`
+    },
+    {
+      name: 'Circular',
+      code: `<Flex gap="large" align="center">
+  <Meter variant="circular" value={60}>
+    <Meter.Track style={{ width: 48, height: 48 }} />
+    <Meter.Value />
+  </Meter>
+  <Meter variant="circular" value={60}>
+    <Meter.Track />
+    <Meter.Value />
+  </Meter>
+  <Meter variant="circular" value={60}>
+    <Meter.Track style={{ width: 96, height: 96, "--rs-meter-track-size": "2px" }} />
+    <Meter.Value />
+  </Meter>
+  <Meter variant="circular" value={60}>
+    <Meter.Track style={{ "--rs-meter-track-size": "8px" }} />
+    <Meter.Value />
+  </Meter>
+</Flex>`
+    }
+  ]
+};
+
+export const withLabelsDemo = {
+  type: 'code',
+  code: `<Flex direction="column" gap="large" style={{ width: "300px" }}>
+  <Meter value={60}>
+    <Flex justify="between">
+      <Meter.Label>CPU Usage</Meter.Label>
+      <Meter.Value />
+    </Flex>
+    <Meter.Track />
+  </Meter>
+  <Meter value={85}>
+    <Flex justify="between">
+      <Meter.Label>Memory</Meter.Label>
+      <Meter.Value />
+    </Flex>
+    <Meter.Track />
+  </Meter>
+</Flex>`
+};
+
+export const customRangeDemo = {
+  type: 'code',
+  code: `<Flex direction="column" gap="large" style={{ width: "300px" }}>
+  <Meter value={750} min={0} max={1000}>
+    <Flex justify="between">
+      <Meter.Label>API Calls</Meter.Label>
+      <Meter.Value />
+    </Flex>
+    <Meter.Track />
+  </Meter>
+</Flex>`
+};

apps/www/src/content/docs/components/meter/index.mdx

@@ -0,0 +1,91 @@
+---
+title: Meter
+description: A graphical display of a numeric value within a known range.
+source: packages/raystack/components/meter
+---
+
+import { playground, directUsageDemo, variantDemo, customizationDemo, withLabelsDemo, customRangeDemo } from "./demo.ts";
+
+<Demo data={playground} />
+
+## Anatomy
+
+Import and assemble the component:
+
+```tsx
+import { Meter } from '@raystack/apsara'
+
+{/* Direct usage — renders track automatically */}
+<Meter value={40} />
+
+{/* Composable usage */}
+<Meter value={40}>
+  <Meter.Label>Storage used</Meter.Label>
+  <Meter.Value />
+  <Meter.Track />
+</Meter>
+```
+
+## API Reference
+
+### Root
+
+The main container for the meter. Renders a default track when no children are provided.
+
+<auto-type-table path="./props.ts" name="MeterProps" />
+
+### Label
+
+Displays a label for the meter.
+
+<auto-type-table path="./props.ts" name="MeterLabelProps" />
+
+### Value
+
+Displays the formatted current value as a percentage.
+
+<auto-type-table path="./props.ts" name="MeterValueProps" />
+
+### Track
+
+Contains the indicator that visualizes the current value.
+
+<auto-type-table path="./props.ts" name="MeterTrackProps" />
+
+## Examples
+
+### Variant
+
+The meter supports `linear` and `circular` variants.
+
+<Demo data={variantDemo} />
+
+### Direct Usage
+
+The simplest way to use the meter. When no children are provided, it renders the track automatically.
+
+<Demo data={directUsageDemo} />
+
+### Customization
+
+Customize the track for both variants. For linear, use `height` on the track. For circular, use `width`/`height` on the track to control the overall size and `--rs-meter-track-size` to control the stroke thickness.
+
+<Demo data={customizationDemo} />
+
+### With Labels
+
+Compose with `Meter.Label` and `Meter.Value` for additional context.
+
+<Demo data={withLabelsDemo} />
+
+### Custom Range
+
+Use `min` and `max` to define custom value ranges.
+
+<Demo data={customRangeDemo} />
+
+## Accessibility
+
+- Uses the `meter` ARIA role
+- Sets `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` attributes
+- Supports `aria-label` and `aria-valuetext` for screen readers

apps/www/src/content/docs/components/meter/props.ts

@@ -0,0 +1,43 @@
+export interface MeterProps {
+  /** The current value of the meter. */
+  value: number;
+
+  /**
+   * Minimum value.
+   * @default 0
+   */
+  min?: number;
+
+  /**
+   * Maximum value.
+   * @default 100
+   */
+  max?: number;
+
+  /**
+   * The visual style of the meter.
+   * @default "linear"
+   */
+  variant?: 'linear' | 'circular';
+
+  /** Additional CSS class name. */
+  className?: string;
+}
+
+export interface MeterLabelProps {
+  /** The label text content. */
+  children: React.ReactNode;
+
+  /** Additional CSS class name. */
+  className?: string;
+}
+
+export interface MeterValueProps {
+  /** Additional CSS class name. */
+  className?: string;
+}
+
+export interface MeterTrackProps {
+  /** Additional CSS class name. */
+  className?: string;
+}

packages/raystack/components/meter/__tests__/meter.test.tsx

@@ -0,0 +1,119 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { Meter } from '../meter';
+import styles from '../meter.module.css';
+
+describe('Meter', () => {
+  describe('Basic Rendering', () => {
+    it('renders meter element', () => {
+      const { container } = render(<Meter value={50} />);
+      const meter = container.querySelector(`.${styles.meter}`);
+      expect(meter).toBeInTheDocument();
+    });
+
+    it('forwards ref correctly', () => {
+      const ref = vi.fn();
+      render(<Meter ref={ref} value={50} />);
+      expect(ref).toHaveBeenCalled();
+    });
+
+    it('applies custom className', () => {
+      const { container } = render(
+        <Meter className='custom-meter' value={50} />
+      );
+      const meter = container.querySelector(`.${styles.meter}`);
+      expect(meter).toHaveClass('custom-meter');
+    });
+
+    it('renders track and indicator by default', () => {
+      const { container } = render(<Meter value={50} />);
+      expect(container.querySelector(`.${styles.track}`)).toBeInTheDocument();
+      expect(
+        container.querySelector(`.${styles.indicator}`)
+      ).toBeInTheDocument();
+    });
+
+    it('renders default track when no children provided', () => {
+      const { container } = render(<Meter value={40} />);
+      expect(container.querySelector(`.${styles.track}`)).toBeInTheDocument();
+    });
+  });
+
+  describe('Variants', () => {
+    it('defaults to linear variant', () => {
+      const { container } = render(<Meter value={50} />);
+      const meter = container.querySelector(`.${styles.meter}`);
+      expect(meter).not.toHaveClass(styles['meter-variant-circular']);
+    });
+
+    it('renders circular variant', () => {
+      const { container } = render(<Meter variant='circular' value={70} />);
+      const meter = container.querySelector(`.${styles.meter}`);
+      expect(meter).toHaveClass(styles['meter-variant-circular']);
+    });
+
+    it('renders SVG track and indicator for circular variant', () => {
+      const { container } = render(<Meter variant='circular' value={70} />);
+      expect(container.querySelector('svg')).toBeInTheDocument();
+      expect(
+        container.querySelector(`.${styles.circularTrackCircle}`)
+      ).toBeInTheDocument();
+      expect(
+        container.querySelector(`.${styles.circularIndicatorCircle}`)
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe('Sub-components', () => {
+    it('renders Label sub-component', () => {
+      render(
+        <Meter value={50}>
+          <Meter.Label>Storage</Meter.Label>
+          <Meter.Track />
+        </Meter>
+      );
+      expect(screen.getByText('Storage')).toBeInTheDocument();
+    });
+
+    it('renders Value sub-component', () => {
+      render(
+        <Meter value={50}>
+          <Meter.Value />
+          <Meter.Track />
+        </Meter>
+      );
+      expect(screen.getByText('50%')).toBeInTheDocument();
+    });
+
+    it('renders custom children instead of default track', () => {
+      const { container } = render(
+        <Meter value={50}>
+          <Meter.Label>Custom</Meter.Label>
+          <Meter.Track />
+        </Meter>
+      );
+      expect(screen.getByText('Custom')).toBeInTheDocument();
+      expect(container.querySelector(`.${styles.track}`)).toBeInTheDocument();
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('has meter role', () => {
+      render(<Meter value={50} aria-label='Storage' />);
+      expect(screen.getByRole('meter')).toBeInTheDocument();
+    });
+
+    it('sets aria-valuenow', () => {
+      render(<Meter value={75} aria-label='Storage' />);
+      const meter = screen.getByRole('meter');
+      expect(meter).toHaveAttribute('aria-valuenow', '75');
+    });
+
+    it('sets aria-valuemin and aria-valuemax', () => {
+      render(<Meter value={50} min={0} max={200} aria-label='Storage' />);
+      const meter = screen.getByRole('meter');
+      expect(meter).toHaveAttribute('aria-valuemin', '0');
+      expect(meter).toHaveAttribute('aria-valuemax', '200');
+    });
+  });
+});

packages/raystack/components/meter/index.tsx

@@ -0,0 +1 @@
+export { Meter } from './meter';