Contribute to npui

General Guidelines

Before you start, please keep the following in mind:

• **Consistency:** Follow the existing code style, naming conventions (kebab-case for slugs, PascalCase for component/hook names), and project structure.
• **Documentation:** Every contribution (component, hook, utility) must come with comprehensive documentation, including a description, code example, and a live preview/usage example.
• **Accessibility:** Ensure your contributions are accessible by following WAI-ARIA guidelines where applicable.
• **Testing:** While not strictly enforced in this environment, consider how your contribution would be tested in a real-world scenario.

Contributing Components

To add a new component to `npui`, follow these steps:

1. **Create Component Files:**

   Create a new directory under `components/npui-components/` with your component's `kebab-case` slug (e.g., `components/npui-components/my-new-component/`). Inside, create:

   • `my-new-component-data.ts`: This file will hold the `PropDetail[]` and `ComponentVariant[]` for your component.
   • Your component's `.tsx` file: If it's a direct `shadcn/ui` re-export, it might live in `components/ui/`. If it's a custom component built on `shadcn/ui` primitives, place it here (e.g., `my-new-component.tsx`).

   Example `my-new-component-data.ts` content:

   my-new-component-data.tsCopy Code

   1// components/npui-components/my-new-component/my-new-component-data.ts
   2import { MyNewComponent } from "@/components/ui/my-new-component"; // Or your custom component path
   3import type { ComponentVariant, PropDetail } from "@/lib/components-data";
   4
   5export const myNewComponentProps: PropDetail[] = [
   6  {
   7    name: "variant",
   8    type: '"default" | "secondary"',
   9    description: "The visual style of the component.",
   10    default: '"default"',
   11  },
   12];
   13
   14export const myNewComponentVariants: ComponentVariant[] = [
   15  {
   16    title: "Default MyNewComponent",
   17    description: "A basic example of MyNewComponent.",
   18    code: `import { MyNewComponent } from "@/components/ui/my-new-component";
   19export function DefaultMyNewComponent() {
   20  return <MyNewComponent>Hello World</MyNewComponent>;
   21}`,
   22    preview: <MyNewComponent>Hello World</MyNewComponent>,
   23  },
   24];

2. **Update Component Registry:**

   Open `lib/components-data.ts`. Import your component's `props` and `variants` from its data file, then add a new `NpuiComponent` object to the `npuiComponents` array.

   lib/components-data.tsCopy Code

   1// lib/components-data.ts
   2// ... other imports
   3import { myNewComponentProps, myNewComponentVariants } from "@/components/npui-components/my-new-component/my-new-component-data";
   4
   5export const npuiComponents: NpuiComponent[] = [
   6  // ... existing components
   7  {
   8    name: "My New Component",
   9    slug: "my-new-component",
   10    description: "A brand new component for npui.",
   11    category: "general", // Or another relevant category
   12    githubUrl: "http://github.com/NextProduction/npui",
   13    npmPackageName: "npui-my-new-component", // Placeholder
   14    props: myNewComponentProps,
   15    variants: myNewComponentVariants,
   16  },
   17];

3. **Ensure Preview:** Make sure the `preview` property in your `ComponentVariant` objects renders a functional and visually representative example of your component. This is crucial for the landing page and docs.

Contributing Hooks

To add a new custom React hook, follow these steps:

1. **Create Hook File:**

   Create a new file under `hooks/` with a `use-` prefix and `kebab-case` slug (e.g., `hooks/use-my-new-hook.ts`).

   hooks/use-my-new-hook.tsCopy Code

   1// hooks/use-my-new-hook.ts
   2"use client"
   3import { useState, useEffect } from "react";
   4import { Button } from "@/components/ui/button"
   5
   6import { Button } from "@/components/ui/button"
   7
   8import { Button } from "@/components/ui/button"
   9
   10import { Button } from "@/components/ui/button"
   11
   12import { Button } from "@/components/ui/button"
   13
   14import { Button } from "@/components/ui/button"
   15
   16import { Button } from "@/components/ui/button"
   17
   18import { Button } from "@/components/ui/button"
   19
   20import { Button } from "@/components/ui/button"
   21
   22import { Button } from "@/components/ui/button"
   23
   24import { Button } from "@/components/ui/button"
   25
   26import { Button } from "@/components/ui/button"
   27
   28import { Button } from "@/components/ui/button"
   29
   30import { Button } from "@/components/ui/button"
   31
   32import { Button } from "@/components/ui/button"
   33
   34import { Button } from "@/components/ui/button"
   35
   36import { Button } from "@/components/ui/button"
   37
   38import { Button } from "@/components/ui/button"
   39
   40import { Button } from "@/components/ui/button"
   41
   42import { Button } from "@/components/ui/button"
   43
   44import { Button } from "@/components/ui/button"
   45
   46import { Button } from "@/components/ui/button"
   47
   48import { Button } from "@/components/ui/button"
   49
   50import { Button } from "@/components/ui/button"
   51
   52import { Button } from "@/components/ui/button"
   53
   54import { Button } from "@/components/ui/button"
   55
   56import { Button } from "@/components/ui/button"
   57
   58import { Button } from "@/components/ui/button"
   59
   60import { Button } from "@/components/ui/button"
   61
   62import { Button } from "@/components/ui/button"
   63
   64
   65export function useMyNewHook(initialValue: number) {
   66  const [count, setCount] = useState(initialValue);
   67
   68  useEffect(() => {
   69    console.log("My new hook is active!");
   70  }, []);
   71
   72  return count;
   73}

2. **Update Hook Registry:**

   Open `lib/hooks-data.ts`. Import your new hook and add a new `HookDetail` object to the `npuiHooks` array. Provide a `code` string and a `usageExample` React node.

   lib/hooks-data.tsCopy Code

   1// lib/hooks-data.ts
   2// ... other imports
   3import { useMyNewHook } from "@/hooks/use-my-new-hook";
   4
   5export const npuiHooks: HookDetail[] = [
   6  // ... existing hooks
   7  {
   8    name: "useMyNewHook",
   9    slug: "use-my-new-hook",
   10    description: "A custom hook that demonstrates a simple counter.",
   11    code: `import { useState, useEffect } from "react";
   12export function useMyNewHook(initialValue: number) {
   13  const [count, setCount] = useState(initialValue);
   14  useEffect(() => {
   15    console.log("My new hook is active!");
   16  }, []);
   17  return count;
   18}`,
   19    usageExample: `import { useMyNewHook } from "@/hooks/use-my-new-hook";
   20export function MyNewHookExample() {
   21  const count = useMyNewHook(0);
   22  return <p>Count from hook: {count}</p>;
   23}`,
   24  },
   25];

Contributing Utilities

To add a new utility function, follow these steps:

1. **Create Utility File:**

   Create a new file under `lib/utils/` with a `kebab-case` slug (e.g., `lib/utils/my-new-utility.ts`).

   lib/utils/my-new-utility.tsCopy Code

   1// lib/utils/my-new-utility.ts
   2/**
   3 * Adds two numbers together.
   4 * @param a The first number.
   5 * @param b The second number.
   6 * @returns The sum of a and b.
   7 */
   8export function addNumbers(a: number, b: number): number {
   9  return a + b;
   10}

2. **Update Utility Registry:**

   Open `lib/utils-data.ts`. Import your new utility and add a new `UtilityDetail` object to the `npuiUtilities` array. Provide a `code` string and a `usageExample` React node.

   lib/utils-data.tsCopy Code

   1// lib/utils-data.ts
   2// ... other imports
   3import { addNumbers } from "@/lib/utils/my-new-utility";
   4
   5export const npuiUtilities: UtilityDetail[] = [
   6  // ... existing utilities
   7  {
   8    name: "addNumbers",
   9    slug: "add-numbers",
   10    description: "A utility function to add two numbers.",
   11    code: `export function addNumbers(a: number, b: number): number {
   12  return a + b;
   13}`,
   14    usageExample: `import { addNumbers } from "@/lib/utils/my-new-utility";
   15export function AddNumbersExample() {
   16  const sum = addNumbers(5, 3);
   17  return <p>5 + 3 = {sum}</p>;
   18}`,
   19  },
   20];