@ponti-studios/ui 0.1.2

package/src/components/forms/stepper.stories.tsx

@@ -0,0 +1,111 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+
+import { booleanControl, hiddenControl, numberControl } from "../../storybook/controls";
+import { Stepper } from "./stepper";
+
+const meta = {
+  title: "Forms/Stepper",
+  component: Stepper,
+  tags: ["autodocs"],
+  argTypes: {
+    value: numberControl("Current value", { defaultValue: 1 }),
+    min: numberControl("Minimum allowed value", { defaultValue: 0 }),
+    max: numberControl("Maximum allowed value", { defaultValue: 100 }),
+    step: numberControl("Amount to change per click", { defaultValue: 1 }),
+    disabled: booleanControl("Prevents user interaction", false),
+    onChange: hiddenControl,
+  },
+} satisfies Meta<typeof Stepper>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+function StepperPreview({
+  value,
+  min,
+  max,
+  step,
+  disabled,
+  format,
+}: {
+  value: number;
+  min?: number;
+  max?: number;
+  step?: number;
+  disabled?: boolean;
+  format?: (value: number) => string;
+}) {
+  const [currentValue, setCurrentValue] = useState(value);
+
+  return (
+    <Stepper
+      value={currentValue}
+      min={min}
+      max={max}
+      step={step}
+      disabled={disabled}
+      format={format}
+      onChange={setCurrentValue}
+    />
+  );
+}
+
+export const Default: Story = {
+  args: {
+    value: 1,
+    min: 0,
+    max: 10,
+    step: 1,
+    onChange: () => {},
+  },
+  render: (args) => (
+    <StepperPreview value={args.value} min={args.min} max={args.max} step={args.step} />
+  ),
+};
+
+export const AtMin: Story = {
+  args: {
+    value: 0,
+    min: 0,
+    max: 10,
+    onChange: () => {},
+  },
+  render: (args) => <StepperPreview value={args.value} min={args.min} max={args.max} />,
+};
+
+export const AtMax: Story = {
+  args: {
+    value: 10,
+    min: 0,
+    max: 10,
+    onChange: () => {},
+  },
+  render: (args) => <StepperPreview value={args.value} min={args.min} max={args.max} />,
+};
+
+export const Disabled: Story = {
+  args: {
+    value: 3,
+    disabled: true,
+    onChange: () => {},
+  },
+  render: (args) => <StepperPreview value={args.value} disabled={args.disabled} />,
+};
+
+export const CustomFormat: Story = {
+  args: {
+    value: 5,
+    min: 0,
+    max: 20,
+    onChange: () => {},
+  },
+  render: (args) => (
+    <StepperPreview
+      value={args.value}
+      min={args.min}
+      max={args.max}
+      format={(value) => `${value} guests`}
+    />
+  ),
+};

package/src/components/forms/stepper.tsx

@@ -0,0 +1,66 @@
+import { Minus, Plus } from "lucide-react";
+
+import { cn } from "../../lib/utils";
+import { Button } from "../primitives/button";
+
+interface StepperProps {
+  value: number;
+  min?: number;
+  max?: number;
+  step?: number;
+  format?: (value: number) => string;
+  onChange: (value: number) => void;
+  className?: string;
+  disabled?: boolean;
+  increaseLabel?: string;
+  decreaseLabel?: string;
+}
+
+function Stepper({
+  value,
+  min = 0,
+  max = 100,
+  step = 1,
+  format,
+  onChange,
+  className,
+  disabled,
+  increaseLabel = "Increase",
+  decreaseLabel = "Decrease",
+}: StepperProps) {
+  const atMin = value <= min;
+  const atMax = value >= max;
+
+  return (
+    <div className={cn("border-default bg-inset flex items-center rounded-lg border", className)}>
+      <Button
+        type="button"
+        variant="ghost"
+        onClick={() => onChange(Math.max(min, value - step))}
+        disabled={disabled || atMin}
+        className="border-default text-secondary rounded-none rounded-l-lg border-r"
+        aria-label={decreaseLabel}
+      >
+        <Minus className="size-3.5" />
+      </Button>
+      <div className="flex min-w-[3ch] flex-1 items-center justify-center px-3">
+        <span className="text-primary font-['Geist'] text-sm font-semibold tabular-nums">
+          {format ? format(value) : value}
+        </span>
+      </div>
+      <Button
+        type="button"
+        variant="ghost"
+        onClick={() => onChange(Math.min(max, value + step))}
+        disabled={disabled || atMax}
+        className="border-default text-secondary rounded-none rounded-r-lg border-l"
+        aria-label={increaseLabel}
+      >
+        <Plus className="size-3.5" />
+      </Button>
+    </div>
+  );
+}
+
+export { Stepper };
+export type { StepperProps };

package/src/components/forms/switch.stories.tsx

@@ -0,0 +1,144 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useEffect, useState } from "react";
+
+import { booleanControl, selectControl } from "../../storybook/controls";
+import { switchSizeOptions } from "../../storybook/options";
+import { Switch } from "./switch";
+
+const meta = {
+  title: "Forms/Switch",
+  component: Switch,
+  tags: ["autodocs"],
+  argTypes: {
+    checked: booleanControl("Controlled on/off state of the switch", false),
+    disabled: booleanControl("Prevents user interaction and applies disabled styling", false),
+    size: selectControl(switchSizeOptions, "Size variant of the switch", {
+      defaultValue: "default",
+    }),
+  },
+} satisfies Meta<typeof Switch>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+function SwitchPreview({
+  checked,
+  disabled = false,
+  id,
+  label,
+  size = "default",
+}: {
+  checked: boolean;
+  disabled: boolean;
+  id: string;
+  label: string;
+  size: "default" | "sm";
+}) {
+  const [currentChecked, setCurrentChecked] = useState(checked);
+
+  useEffect(() => {
+    setCurrentChecked(checked);
+  }, [checked]);
+
+  return (
+    <div className="flex items-center space-x-2">
+      <Switch
+        id={id}
+        checked={currentChecked}
+        disabled={disabled}
+        onCheckedChange={setCurrentChecked}
+        size={size}
+      />
+      <label htmlFor={id} className="text-primary text-sm leading-none font-medium">
+        {label}
+      </label>
+    </div>
+  );
+}
+
+export const Default: Story = {
+  args: {
+    checked: false,
+  },
+  render: (args) => (
+    <SwitchPreview
+      checked={args.checked ?? false}
+      disabled={args.disabled ?? false}
+      id="switch-default"
+      label="Airplane Mode"
+      size={args.size ?? "default"}
+    />
+  ),
+};
+
+export const WithLabel: Story = {
+  args: {
+    checked: false,
+    size: "default",
+  },
+  render: (args) => (
+    <SwitchPreview
+      checked={args.checked ?? false}
+      disabled={args.disabled ?? false}
+      id="airplane-mode"
+      label="Airplane Mode"
+      size={args.size ?? "default"}
+    />
+  ),
+};
+
+export const Checked: Story = {
+  args: {
+    checked: true,
+  },
+  render: (args) => (
+    <SwitchPreview
+      checked={args.checked ?? true}
+      disabled={args.disabled ?? false}
+      id="notifications"
+      label="Enable Notifications"
+      size={args.size ?? "default"}
+    />
+  ),
+};
+
+export const Disabled: Story = {
+  args: {
+    checked: false,
+    disabled: true,
+  },
+  render: (args) => (
+    <div className="flex flex-col gap-3">
+      <SwitchPreview
+        checked={args.checked ?? false}
+        disabled={args.disabled ?? false}
+        id="disabled-off"
+        label="Disabled off"
+        size={args.size ?? "default"}
+      />
+      <SwitchPreview
+        checked
+        disabled={args.disabled ?? false}
+        id="disabled-on"
+        label="Disabled on"
+        size={args.size ?? "default"}
+      />
+    </div>
+  ),
+};
+
+export const Small: Story = {
+  args: {
+    checked: false,
+    size: "sm",
+  },
+  render: (args) => (
+    <SwitchPreview
+      checked={args.checked ?? false}
+      disabled={args.disabled ?? false}
+      id="small"
+      label="Small switch"
+      size={args.size ?? "default"}
+    />
+  ),
+};

package/src/components/forms/switch.tsx

@@ -0,0 +1,36 @@
+import * as SwitchPrimitive from "@radix-ui/react-switch";
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+
+function Switch({
+  className,
+  size = "default",
+  ...props
+}: React.ComponentProps<typeof SwitchPrimitive.Root> & {
+  size?: "sm" | "default";
+}) {
+  return (
+    <SwitchPrimitive.Root
+      data-slot="switch"
+      data-size={size}
+      className={cn(
+        "peer data-[state=checked]:bg-accent data-[state=unchecked]:bg-inset focus-visible:ring-focus inline-flex shrink-0 items-center rounded-full border border-transparent p-px focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:justify-end data-[state=unchecked]:justify-start",
+        size === "default" ? "h-[1.15rem] w-8" : "h-3.5 w-6",
+        className,
+      )}
+      {...props}
+    >
+      <SwitchPrimitive.Thumb
+        data-slot="switch-thumb"
+        data-size={size}
+        className={cn(
+          "pointer-events-none block rounded-full bg-white shadow-sm ring-1 ring-black/5 transition-all",
+          size === "default" ? "size-4" : "size-3",
+        )}
+      />
+    </SwitchPrimitive.Root>
+  );
+}
+
+export { Switch };

package/src/components/forms/text-field.stories.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, within } from "storybook/test";
+
+import { booleanControl, selectControl, textControl } from "../../storybook/controls";
+import { textFieldTypeOptions } from "../../storybook/options";
+import { TextField } from "./text-field";
+
+const meta = {
+  title: "Forms/TextField",
+  component: TextField,
+  tags: ["autodocs"],
+  argTypes: {
+    label: textControl("Label displayed above the field"),
+    type: selectControl(textFieldTypeOptions, "Input type used by the field", {
+      defaultValue: "text",
+    }),
+    placeholder: textControl("Placeholder text shown when the field is empty"),
+    helpText: textControl("Supporting text shown below the field"),
+    error: textControl("Validation error text shown below the field"),
+    disabled: booleanControl("Prevents user interaction and applies disabled styling", false),
+    required: booleanControl("Marks the field as required for form submission", false),
+  },
+} satisfies Meta<typeof TextField>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    label: "Email",
+    placeholder: "you@example.com",
+    type: "email",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByLabelText("Email");
+
+    await userEvent.click(input);
+    await userEvent.type(input, "you@example.com");
+
+    await expect(input).toHaveFocus();
+    await expect(input).toHaveValue("you@example.com");
+  },
+};
+
+export const WithHelpText: Story = {
+  args: {
+    label: "Search",
+    helpText: "Press Enter to submit",
+    placeholder: "Search notes",
+    type: "search",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await expect(canvas.getByText("Press Enter to submit")).toBeInTheDocument();
+    await expect(canvas.getByLabelText("Search")).toBeEnabled();
+  },
+};
+
+export const Error: Story = {
+  args: {
+    label: "Password",
+    error: "Password is required",
+    type: "password",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByLabelText("Password");
+
+    await expect(input).toHaveAttribute("aria-invalid", "true");
+    await expect(canvas.getByText("Password is required")).toBeInTheDocument();
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    label: "Handle",
+    placeholder: "@hominem",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await expect(canvas.getByLabelText("Handle")).toBeDisabled();
+  },
+};

package/src/components/forms/text-field.tsx

@@ -0,0 +1,40 @@
+import * as React from "react";
+
+import { Field } from "./field";
+import { Input } from "./input";
+import type { TextFieldBaseProps, TextFieldType } from "./text-field.types";
+
+interface TextFieldProps extends Omit<React.ComponentProps<"input">, "type">, TextFieldBaseProps {
+  type?: TextFieldType | undefined;
+}
+
+/**
+ * TextField — composed input with label, helper text, and error state.
+ * Replaces raw `<input>` + `<label>` + error span patterns in feature code.
+ *
+ * @example
+ * <TextField label="Email" type="email" error={errors.email?.message} />
+ * <TextField label="Search" type="search" helpText="Press Enter to search" />
+ */
+function TextField({
+  id,
+  label,
+  helpText,
+  error,
+  className,
+  disabled,
+  type = "text",
+  ...inputProps
+}: TextFieldProps) {
+  if (!label && !helpText && !error) {
+    return <Input className={className} disabled={disabled} type={type} {...inputProps} />;
+  }
+
+  return (
+    <Field id={id} label={label} helpText={helpText} error={error}>
+      <Input className={className} disabled={disabled} type={type} {...inputProps} />
+    </Field>
+  );
+}
+
+export { TextField, type TextFieldProps };

package/src/components/forms/text-field.types.ts

@@ -0,0 +1,9 @@
+export type TextFieldType = "text" | "email" | "password" | "search";
+
+export interface TextFieldBaseProps {
+  disabled?: boolean | undefined;
+  error?: string | undefined;
+  helpText?: string | undefined;
+  label?: string | undefined;
+  id?: string | undefined;
+}

package/src/components/forms/textarea.stories.tsx

@@ -0,0 +1,150 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { ComponentProps } from "react";
+import { expect, userEvent, within } from "storybook/test";
+
+import { booleanControl, numberControl, textControl } from "../../storybook/controls";
+import { Textarea } from "./textarea";
+
+function TextareaField({
+  error,
+  helpText,
+  id,
+  label,
+  ...props
+}: ComponentProps<typeof Textarea> & {
+  error?: string;
+  helpText?: string;
+  id: string;
+  label: string;
+}) {
+  const helpId = helpText ? `${id}-help` : undefined;
+  const errorId = error ? `${id}-error` : undefined;
+
+  return (
+    <div className="grid gap-2">
+      <label htmlFor={id} className="text-primary text-sm leading-none font-medium">
+        {label}
+      </label>
+      <Textarea
+        id={id}
+        aria-describedby={[helpId, errorId].filter(Boolean).join(" ") || undefined}
+        aria-invalid={error ? true : undefined}
+        {...props}
+      />
+      {helpText ? (
+        <p id={helpId} className="text-secondary text-sm">
+          {helpText}
+        </p>
+      ) : null}
+      {error ? (
+        <p id={errorId} className="text-destructive text-sm" role="alert">
+          {error}
+        </p>
+      ) : null}
+    </div>
+  );
+}
+
+const meta = {
+  title: "Forms/Textarea",
+  component: Textarea,
+  tags: ["autodocs"],
+  argTypes: {
+    placeholder: textControl("Placeholder text shown when the textarea is empty"),
+    rows: numberControl("Number of visible text lines", { min: 1, max: 20, defaultValue: 4 }),
+    disabled: booleanControl("Prevents user interaction and applies disabled styling", false),
+  },
+} satisfies Meta<typeof Textarea>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    placeholder: "Enter your notes here",
+    rows: 4,
+  },
+  render: (args) => <TextareaField id="notes" label="Notes" {...args} />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const textarea = canvas.getByLabelText("Notes") as HTMLTextAreaElement;
+
+    await userEvent.click(textarea);
+    await userEvent.type(textarea, "Sample note content");
+
+    await expect(textarea).toHaveValue("Sample note content");
+    await expect(textarea).toHaveFocus();
+  },
+};
+
+export const WithHelpText: Story = {
+  args: {
+    placeholder: "Write a detailed description...",
+    rows: 5,
+  },
+  render: (args) => (
+    <TextareaField
+      id="description"
+      label="Description"
+      helpText="Markdown formatting is supported"
+      {...args}
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await expect(canvas.getByText("Markdown formatting is supported")).toBeInTheDocument();
+  },
+};
+
+export const Error: Story = {
+  args: {
+    placeholder: "Write something...",
+    rows: 3,
+  },
+  render: (args) => (
+    <TextareaField
+      id="message"
+      label="Message"
+      error="Message is required and cannot be empty"
+      {...args}
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+
+    await expect(canvas.getByRole("alert")).toHaveTextContent(
+      "Message is required and cannot be empty",
+    );
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    placeholder: "This field is disabled",
+    rows: 4,
+  },
+  render: (args) => <TextareaField id="archived-notes" label="Archived Notes" {...args} />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const textarea = canvas.getByLabelText("Archived Notes");
+
+    await expect(textarea).toBeDisabled();
+  },
+};
+
+export const LargeField: Story = {
+  args: {
+    placeholder: "Write as much as you need...",
+    rows: 8,
+  },
+  render: (args) => (
+    <TextareaField
+      id="long-form-content"
+      label="Long Form Content"
+      helpText="Use this field for extended writing"
+      {...args}
+    />
+  ),
+};

package/src/components/forms/textarea.tsx

@@ -0,0 +1,18 @@
+import * as React from "react";
+
+import { cn } from "../../lib/utils";
+
+function Textarea({ className, ...props }: React.ComponentProps<"textarea">) {
+  return (
+    <textarea
+      data-slot="textarea"
+      className={cn(
+        "placeholder:text-secondary aria-invalid:ring-destructive/20 aria-invalid:border-destructive focus-visible:ring-focus flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base transition-colors focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { Textarea };

package/src/components/layout/index.ts

@@ -0,0 +1,2 @@
+export { ScrollArea } from "./scroll-area";
+export type { ScrollAreaProps } from "./scroll-area";