nebula-component-creation（星云组件创建）

Story requirements are delegated to nebula-storybook-stories (canonical source for story naming, structure, and CSF details).

Workflow

Creating a new component

Always start from an example. When asked to create a new component:

1. Find a similar example in examples/components/ that can serve as a starting point (e.g., use blockquote for an "alert" component, or button for any interactive element)
2. Copy the example component folder to src/components/<new_name>/
3. Copy the corresponding story from examples/stories/ to src/stories/
4. Modify the copied files to implement the new component

Always copy or create a story file for each component. For story naming, structure, and CSF conventions, follow nebula-storybook-stories. Follow its "Name Mapping" section for filename/path conversions.

This approach ensures consistent patterns for component.yml structure, JSX conventions, and Storybook story format across all components.

# Example: Create an Alert component based on Blockquote
cp -r examples/components/blockquote src/components/alert
cp examples/stories/blockquote.stories.jsx src/stories/alert.stories.jsx

Then modify the copied files to implement the Alert component.

Components use the @/components import alias, which points to src/components. When you copy and modify examples, the imports will work automatically.

Copying an existing example component

Workflow for copying example components:

1. Check for existing example: If the requested component (e.g., "hero") exists in examples/components/, plan to copy it directly.
2. Analyze dependencies: Read the example component's index.jsx file and identify all @/components/<name> imports. These are component dependencies.
3. Recursively discover nested dependencies: For each dependency found, check its index.jsx for additional @/components/<name> imports. Continue until all dependencies are discovered. For example, hero imports two_column_text, which imports heading and text.
4. Check what already exists: List the contents of src/components/ to see which components are already present.
5. Copy only missing components: Copy only the example components (and their stories) that don't already exist in src/components/. Do NOT overwrite existing components.

Example scenario: User asks for a "hero" component.

# Step 1: Check existing components in src/
ls src/components/

# Suppose output shows only: button/  global.css

# Step 2: Analyze hero dependencies (hero → two_column_text → heading, text)
# Missing components: hero, two_column_text, heading, text
# button already exists, so skip it if it were a dependency

# Step 3: Copy all missing components and stories in one batch
cp -r examples/components/hero src/components/
cp -r examples/components/two_column_text src/components/
cp -r examples/components/heading src/components/
cp -r examples/components/text src/components/

cp examples/stories/hero.stories.jsx src/stories/
cp examples/stories/two-column-text.stories.jsx src/stories/
cp examples/stories/heading.stories.jsx src/stories/
cp examples/stories/text.stories.jsx src/stories/

Required component folder structure

CRITICAL: Every component folder in src/components/ MUST contain exactly two files:

src/components/<component-name>/
├── index.jsx      # React component implementation
└── component.yml  # Component metadata and props for Drupal Canvas

Never create a component folder without both files. The index.jsx contains the actual React component implementation. The component.yml defines the component's metadata, props, and slots for Drupal Canvas.

The directory name must match machineName. The component folder name must exactly match the machineName value defined in component.yml. Use kebab-case (with hyphens) for new and modified components in src/components/.

Legacy exception: examples/components/ may contain legacy snake_case names. Keep those examples unchanged unless explicitly asked to migrate them.

After creating components, verify the folder structure:

# List all component folders and their contents
ls -la src/components/*/

# Verify each new component has both required files
ls src/components/<component-name>/index.jsx
ls src/components/<component-name>/component.yml

If a component folder is missing either file, the component is incomplete and will not work. Both index.jsx and component.yml are required.

Best practices

Reuse existing components

Always check src/components/ before creating new UI elements. When building a component that needs common UI elements (buttons, headings, images, etc.), import and use existing components rather than duplicating their functionality.

If the component you need doesn't exist in src/components/ yet, check if it exists in examples/components/. If so, copy it to src/components/ first (see "Copying an Existing Example Component" above), then import and use it.

// Correct
import Button from "@/components/button";

const NewsletterSignup = ({ onSubmit }) => (
  <form onSubmit={onSubmit}>
    <input type="email" placeholder="Enter your email" />
    <Button variant="primary">Subscribe</Button>
  </form>
);

// Wrong
const NewsletterSignup = ({ onSubmit }) => (
  <form onSubmit={onSubmit}>
    <input type="email" placeholder="Enter your email" />
    <button className="rounded bg-primary-600 px-4 py-2 text-white">
      Subscribe
    </button>
  </form>
);

Common pitfalls

• Overwriting existing components - Always check src/components/ first
• Missing dependencies - Recursively check all @/components/ imports
• Incomplete component folder - Both index.jsx and component.yml are required
• Ignoring the @/components alias - Use this import alias; it points to src/components