@tribepad/themis 1.0.5 → 1.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribepad/themis",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Accessible React component library built on React Aria primitives",
   "author": "Tribepad <mbasford@tribepad.com>",
   "license": "MIT",

package/src/elements/MatrixGrid/MatrixGrid.stories.tsx

@@ -0,0 +1,292 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { MatrixGrid } from './MatrixGrid';
+
+const LIKERT_COLUMNS = [
+  { id: 'sd', label: 'Strongly Disagree' },
+  { id: 'd', label: 'Disagree' },
+  { id: 'n', label: 'Neutral' },
+  { id: 'a', label: 'Agree' },
+  { id: 'sa', label: 'Strongly Agree' },
+];
+
+const LIKERT_ROWS = [
+  { id: 'q1', label: 'The product meets my needs' },
+  { id: 'q2', label: 'The product is easy to use' },
+  { id: 'q3', label: 'The product is reliable' },
+];
+
+const meta = {
+  title: 'Elements/MatrixGrid',
+  component: MatrixGrid,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Grid-style survey question with rows (statements) and columns (rating options). Each row has a single radio selection. Built with role="grid" ARIA pattern for 2D keyboard navigation.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['sm', 'default', 'lg'],
+      description: 'Component size',
+      table: { defaultValue: { summary: 'default' } },
+    },
+    isDisabled: { control: 'boolean' },
+    isReadOnly: { control: 'boolean' },
+    isRequired: { control: 'boolean' },
+    isInvalid: { control: 'boolean' },
+    label: { control: 'text' },
+    description: { control: 'text' },
+    errorMessage: { control: 'text' },
+  },
+} satisfies Meta<typeof MatrixGrid>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// =============================================================================
+// Default
+// =============================================================================
+
+export const Default: Story = {
+  args: {
+    label: 'Product Evaluation',
+    rows: LIKERT_ROWS,
+    columns: LIKERT_COLUMNS,
+  },
+};
+
+// =============================================================================
+// Large Matrix
+// =============================================================================
+
+export const LargeMatrix: Story = {
+  args: {
+    label: 'Comprehensive Service Assessment',
+    rows: [
+      { id: 'q1', label: 'Quality of service' },
+      { id: 'q2', label: 'Value for money' },
+      { id: 'q3', label: 'Staff friendliness' },
+      { id: 'q4', label: 'Wait time' },
+      { id: 'q5', label: 'Cleanliness of facility' },
+      { id: 'q6', label: 'Ease of scheduling' },
+      { id: 'q7', label: 'Communication clarity' },
+      { id: 'q8', label: 'Follow-up care' },
+    ],
+    columns: [
+      { id: 'vp', label: 'Very Poor' },
+      { id: 'p', label: 'Poor' },
+      { id: 'f', label: 'Fair' },
+      { id: 'g', label: 'Good' },
+      { id: 'vg', label: 'Very Good' },
+      { id: 'e', label: 'Excellent' },
+      { id: 'na', label: 'N/A' },
+    ],
+  },
+  parameters: {
+    docs: {
+      description: { story: 'Large matrix with 8 rows and 7 columns. Scrolls horizontally on small screens.' },
+    },
+  },
+};
+
+// =============================================================================
+// Sizes
+// =============================================================================
+
+export const AllSizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <MatrixGrid
+        label="Small"
+        rows={LIKERT_ROWS.slice(0, 2)}
+        columns={LIKERT_COLUMNS}
+        size="sm"
+      />
+      <MatrixGrid
+        label="Default"
+        rows={LIKERT_ROWS.slice(0, 2)}
+        columns={LIKERT_COLUMNS}
+        size="default"
+      />
+      <MatrixGrid
+        label="Large"
+        rows={LIKERT_ROWS.slice(0, 2)}
+        columns={LIKERT_COLUMNS}
+        size="lg"
+      />
+    </div>
+  ),
+};
+
+// =============================================================================
+// States
+// =============================================================================
+
+export const Disabled: Story = {
+  args: {
+    label: 'Survey (Closed)',
+    rows: LIKERT_ROWS,
+    columns: LIKERT_COLUMNS,
+    value: { q1: 'a', q2: 'sa', q3: 'n' },
+    isDisabled: true,
+  },
+};
+
+export const ReadOnly: Story = {
+  args: {
+    label: 'Previous Responses',
+    rows: LIKERT_ROWS,
+    columns: LIKERT_COLUMNS,
+    value: { q1: 'sa', q2: 'a', q3: 'n' },
+    isReadOnly: true,
+  },
+};
+
+export const Required: Story = {
+  args: {
+    label: 'Required Assessment',
+    rows: LIKERT_ROWS,
+    columns: LIKERT_COLUMNS,
+    isRequired: true,
+  },
+};
+
+export const Invalid: Story = {
+  args: {
+    label: 'Assessment',
+    rows: LIKERT_ROWS,
+    columns: LIKERT_COLUMNS,
+    isInvalid: true,
+    errorMessage: 'Please answer all rows before continuing.',
+  },
+};
+
+export const WithDescription: Story = {
+  args: {
+    label: 'Training Effectiveness',
+    description: 'Rate each aspect of the training programme you attended.',
+    rows: LIKERT_ROWS,
+    columns: LIKERT_COLUMNS,
+  },
+};
+
+// =============================================================================
+// Controlled Example
+// =============================================================================
+
+export const ControlledExample: Story = {
+  render: () => {
+    const [value, setValue] = useState<Record<string, string | null>>({});
+    return (
+      <div className="max-w-2xl">
+        <MatrixGrid
+          label="Controlled Matrix"
+          rows={LIKERT_ROWS}
+          columns={LIKERT_COLUMNS}
+          value={value}
+          onChange={setValue}
+        />
+        <pre className="mt-4 rounded bg-[var(--muted)] p-3 text-xs">
+          {JSON.stringify(value, null, 2)}
+        </pre>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: { story: 'Controlled component with state displayed below.' },
+    },
+  },
+};
+
+// =============================================================================
+// Real-world Examples
+// =============================================================================
+
+export const SatisfactionSurvey: Story = {
+  render: () => {
+    const [value, setValue] = useState<Record<string, string | null>>({});
+    const rows = [
+      { id: 'onboarding', label: 'Onboarding process' },
+      { id: 'tools', label: 'Tools and resources' },
+      { id: 'management', label: 'Management support' },
+      { id: 'culture', label: 'Company culture' },
+      { id: 'growth', label: 'Growth opportunities' },
+    ];
+    const columns = [
+      { id: 'vs', label: 'Very Unsatisfied' },
+      { id: 's', label: 'Unsatisfied' },
+      { id: 'n', label: 'Neutral' },
+      { id: 'st', label: 'Satisfied' },
+      { id: 'vst', label: 'Very Satisfied' },
+    ];
+    const answered = Object.keys(value).length;
+    return (
+      <div className="max-w-2xl rounded-lg border border-[var(--border)] bg-[var(--content-background)] p-6">
+        <MatrixGrid
+          label="Employee Satisfaction Survey"
+          description="Please rate your satisfaction with each aspect of your role."
+          rows={rows}
+          columns={columns}
+          value={value}
+          onChange={setValue}
+          isRequired
+        />
+        <p className="mt-3 text-sm text-[var(--muted-foreground)]">
+          {answered} of {rows.length} answered
+        </p>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: { story: 'Employee satisfaction survey with progress indicator.' },
+    },
+  },
+};
+
+export const EmployeeFeedback: Story = {
+  args: {
+    label: 'Peer Feedback',
+    description: 'Rate your colleague on the following competencies.',
+    rows: [
+      { id: 'comm', label: 'Communication' },
+      { id: 'team', label: 'Teamwork' },
+      { id: 'init', label: 'Initiative' },
+      { id: 'quality', label: 'Quality of work' },
+      { id: 'time', label: 'Time management' },
+    ],
+    columns: [
+      { id: 'ni', label: 'Needs Improvement' },
+      { id: 'me', label: 'Meets Expectations' },
+      { id: 'ee', label: 'Exceeds Expectations' },
+      { id: 'ex', label: 'Exceptional' },
+    ],
+    isRequired: true,
+  },
+  parameters: {
+    docs: {
+      description: { story: '360-degree feedback form with 4-point competency scale.' },
+    },
+  },
+};
+
+export const CustomStyling: Story = {
+  args: {
+    label: 'Custom Styled Grid',
+    rows: LIKERT_ROWS.slice(0, 2),
+    columns: LIKERT_COLUMNS.slice(0, 3),
+    className: 'p-4 rounded-lg border border-[var(--border)] bg-[var(--content-background)]',
+  },
+  parameters: {
+    docs: {
+      description: { story: 'Demonstrates custom className pass-through for container styling.' },
+    },
+  },
+};

package/src/elements/RatingScale/RatingScale.stories.tsx

@@ -0,0 +1,379 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { RatingScale } from './RatingScale';
+
+const meta = {
+  title: 'Elements/RatingScale',
+  component: RatingScale,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Configurable rating scale with 3 display styles (buttons, stars, slider). Built on React Aria RadioGroup and Slider primitives for full keyboard and screen reader support.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    displayStyle: {
+      control: 'select',
+      options: ['buttons', 'stars', 'slider'],
+      description: 'Visual display style of the scale',
+      table: { defaultValue: { summary: 'buttons' } },
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'default', 'lg'],
+      description: 'Component size',
+      table: { defaultValue: { summary: 'default' } },
+    },
+    min: { control: 'number', description: 'Minimum value', table: { defaultValue: { summary: '1' } } },
+    max: { control: 'number', description: 'Maximum value', table: { defaultValue: { summary: '5' } } },
+    step: { control: 'number', description: 'Step increment', table: { defaultValue: { summary: '1' } } },
+    showNA: { control: 'boolean', description: 'Show N/A button', table: { defaultValue: { summary: 'false' } } },
+    isDisabled: { control: 'boolean' },
+    isReadOnly: { control: 'boolean' },
+    isRequired: { control: 'boolean' },
+    isInvalid: { control: 'boolean' },
+    label: { control: 'text' },
+    description: { control: 'text' },
+    errorMessage: { control: 'text' },
+    lowLabel: { control: 'text' },
+    highLabel: { control: 'text' },
+  },
+} satisfies Meta<typeof RatingScale>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// =============================================================================
+// Display Styles
+// =============================================================================
+
+export const Buttons: Story = {
+  args: {
+    label: 'How would you rate this experience?',
+    displayStyle: 'buttons',
+  },
+};
+
+export const Stars: Story = {
+  args: {
+    label: 'Rate this product',
+    displayStyle: 'stars',
+  },
+};
+
+export const Slider: Story = {
+  args: {
+    label: 'Satisfaction level',
+    displayStyle: 'slider',
+  },
+};
+
+export const AllDisplayStyles: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8 w-[400px]">
+      <RatingScale label="Buttons" displayStyle="buttons" />
+      <RatingScale label="Stars" displayStyle="stars" />
+      <RatingScale label="Slider" displayStyle="slider" />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: { story: 'Comparison of all three display styles.' },
+    },
+  },
+};
+
+// =============================================================================
+// Sizes
+// =============================================================================
+
+export const SmallSize: Story = {
+  args: {
+    label: 'Small rating',
+    size: 'sm',
+  },
+};
+
+export const LargeSize: Story = {
+  args: {
+    label: 'Large rating',
+    size: 'lg',
+  },
+};
+
+export const AllSizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8 w-[400px]">
+      <RatingScale label="Small" size="sm" />
+      <RatingScale label="Default" size="default" />
+      <RatingScale label="Large" size="lg" />
+    </div>
+  ),
+};
+
+// =============================================================================
+// Labels
+// =============================================================================
+
+export const WithEndpointLabels: Story = {
+  args: {
+    label: 'Job satisfaction',
+    lowLabel: 'Very unsatisfied',
+    highLabel: 'Very satisfied',
+  },
+};
+
+export const WithValueLabels: Story = {
+  render: () => {
+    const [value, setValue] = useState<number | null>(null);
+    return (
+      <div className="w-[400px]">
+        <RatingScale
+          label="How likely are you to recommend us?"
+          value={value}
+          onChange={setValue}
+          valueLabels={{
+            '1': 'Not at all likely',
+            '2': 'Unlikely',
+            '3': 'Neutral',
+            '4': 'Likely',
+            '5': 'Very likely',
+          }}
+        />
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: { story: 'Value labels provide context for each score.' },
+    },
+  },
+};
+
+export const WithDescription: Story = {
+  args: {
+    label: 'Technical skills',
+    description: 'Rate the candidate\'s technical proficiency from 1-5.',
+  },
+};
+
+// =============================================================================
+// N/A Support
+// =============================================================================
+
+export const WithNA: Story = {
+  render: () => {
+    const [value, setValue] = useState<number | null>(null);
+    return (
+      <div className="w-[400px]">
+        <RatingScale
+          label="Communication skills"
+          showNA
+          value={value}
+          onChange={setValue}
+          lowLabel="Poor"
+          highLabel="Excellent"
+        />
+        <p className="mt-2 text-sm text-[var(--muted-foreground)]">
+          Selected: {value === null ? 'N/A' : value ?? 'None'}
+        </p>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: { story: 'N/A button allows opting out of rating.' },
+    },
+  },
+};
+
+// =============================================================================
+// States
+// =============================================================================
+
+export const Required: Story = {
+  args: {
+    label: 'Rating',
+    isRequired: true,
+  },
+};
+
+export const Invalid: Story = {
+  args: {
+    label: 'Rating',
+    isInvalid: true,
+    errorMessage: 'Please select a rating before continuing.',
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    label: 'Rating',
+    value: 3,
+    isDisabled: true,
+  },
+};
+
+export const ReadOnly: Story = {
+  args: {
+    label: 'Previous rating',
+    value: 4,
+    isReadOnly: true,
+  },
+};
+
+// =============================================================================
+// Custom Ranges
+// =============================================================================
+
+export const TenPointScale: Story = {
+  args: {
+    label: 'NPS Score',
+    min: 0,
+    max: 10,
+    lowLabel: 'Not likely',
+    highLabel: 'Very likely',
+    displayStyle: 'buttons',
+  },
+  parameters: {
+    docs: {
+      description: { story: '0-10 Net Promoter Score scale.' },
+    },
+  },
+};
+
+export const StarsOutOfTen: Story = {
+  args: {
+    label: 'Movie rating',
+    min: 1,
+    max: 10,
+    displayStyle: 'stars',
+  },
+};
+
+export const SliderWithEndpoints: Story = {
+  args: {
+    label: 'Pain level',
+    min: 0,
+    max: 10,
+    displayStyle: 'slider',
+    lowLabel: 'No pain',
+    highLabel: 'Worst pain',
+  },
+};
+
+// =============================================================================
+// Controlled Example
+// =============================================================================
+
+export const ControlledExample: Story = {
+  render: () => {
+    const [value, setValue] = useState<number | null>(3);
+    return (
+      <div className="w-[400px]">
+        <RatingScale
+          label="Controlled rating"
+          value={value}
+          onChange={setValue}
+          displayStyle="buttons"
+          showNA
+          lowLabel="Low"
+          highLabel="High"
+          valueLabels={{
+            '1': 'Poor',
+            '2': 'Below average',
+            '3': 'Average',
+            '4': 'Above average',
+            '5': 'Excellent',
+          }}
+        />
+        <div className="mt-4 flex gap-2">
+          <button
+            className="rounded border px-3 py-1 text-sm"
+            onClick={() => setValue(1)}
+          >
+            Set to 1
+          </button>
+          <button
+            className="rounded border px-3 py-1 text-sm"
+            onClick={() => setValue(5)}
+          >
+            Set to 5
+          </button>
+          <button
+            className="rounded border px-3 py-1 text-sm"
+            onClick={() => setValue(null)}
+          >
+            Set N/A
+          </button>
+        </div>
+      </div>
+    );
+  },
+};
+
+// =============================================================================
+// Real-world Examples
+// =============================================================================
+
+export const InterviewScorecard: Story = {
+  render: () => {
+    const [scores, setScores] = useState<Record<string, number | null>>({
+      technical: null,
+      communication: null,
+      leadership: null,
+    });
+    return (
+      <div className="w-[500px] rounded-lg border border-[var(--border)] bg-[var(--content-background)] p-6">
+        <h3 className="mb-4 text-lg font-semibold text-[var(--content-foreground)]">
+          Interview Scorecard
+        </h3>
+        <div className="flex flex-col gap-6">
+          <RatingScale
+            label="Technical Skills"
+            displayStyle="stars"
+            value={scores.technical}
+            onChange={(v) => setScores((s) => ({ ...s, technical: v }))}
+            showNA
+          />
+          <RatingScale
+            label="Communication"
+            displayStyle="buttons"
+            value={scores.communication}
+            onChange={(v) => setScores((s) => ({ ...s, communication: v }))}
+            lowLabel="Poor"
+            highLabel="Excellent"
+            valueLabels={{
+              '1': 'Poor',
+              '2': 'Below expectations',
+              '3': 'Meets expectations',
+              '4': 'Exceeds expectations',
+              '5': 'Outstanding',
+            }}
+          />
+          <RatingScale
+            label="Leadership Potential"
+            displayStyle="slider"
+            value={scores.leadership}
+            onChange={(v) => setScores((s) => ({ ...s, leadership: v }))}
+            min={1}
+            max={10}
+            lowLabel="Low"
+            highLabel="High"
+          />
+        </div>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Interview scorecard showing all three display styles for different evaluation criteria.',
+      },
+    },
+  },
+};