feat(material): add material package

[chilingling]

English | 简体中文

PR

PR Checklist

Please check if your PR fulfills the following requirements:

• [x] The commit message follows our Commit Message Guidelines
• [ ] Tests for the changes have been added (for bug fixes / features)
• [ ] Docs have been added / updated (for bug fixes / features)
• [ ] Built its own designer, fully self-validated

PR Type

What kind of change does this PR introduce?

• [ ] Bugfix
• [x] Feature
• [ ] Code style update (formatting, local variables)
• [ ] Refactoring (no functional changes, no api changes)
• [ ] Build related changes
• [ ] CI related changes
• [ ] Documentation content changes
• [ ] Other... Please describe:

Background and solution

What is the current behavior?

Issue Number: N/A

What is the new behavior?

Does this PR introduce a breaking change?

• [x] Yes
• [ ] No

Other information

Summary by CodeRabbit

• New Features

  • Engine now loads materials from a module-based source for more flexible and maintainable material usage.
  • Added a material build/serve tool with build and watch/serve modes to generate and serve material bundles for easier development.

• Chores

  • Added the materials package dependency to support the new module-based material source.

[coderabbitai[bot]]

Walkthrough

Replaced a static materials JSON in the designer-demo engine config with an imported @opentiny/tiny-engine-materials module and added that dependency; added a new materials build/serve CLI script packages/materials/buildMaterials.mjs that builds bundles, optionally combines them, watches files, and can serve the dist folder.

Changes

Cohort / File(s)	Change Summaries
Designer demo config designer-demo/engine.config.js	Replaced material: ['/mock/bundle.json'] with material: [material], switching material source from a static JSON file to an imported module.
Designer demo deps designer-demo/package.json	Added dependency "@opentiny/tiny-engine-materials": "workspace:*" under dependencies.
Materials builder CLI packages/materials/buildMaterials.mjs	Added a new CLI module that: scans materials directories, validates component JSON and optional meta.json, emits per-entry entry.json and entry.compsMap.json, optionally combines outputs into dist/index.json and dist/index.compsMap.json, supports build, build:split, and serve commands, watches files in serve mode, and can start a static HTTP server to serve dist.

Sequence Diagram(s)

sequenceDiagram
  participant DevCLI as CLI
  participant Builder as MaterialsBuilder
  participant FS as FileSystem
  participant HTTP as StaticServer
  rect rgb(230,248,255)
    DevCLI->>Builder: run build / build:split / serve
    opt build or build:split
      Builder->>FS: read materials/*/*.json, meta.json
      Builder->>Builder: validate & generate bundles
      Builder->>FS: write dist/entry.json, entry.compsMap.json
      alt build (combine)
        Builder->>FS: write dist/index.json, index.compsMap.json
      end
    end
    opt serve
      Builder->>FS: initial build
      Builder->>FS: watch files (add/change/unlink)
      FS->>Builder: file change events
      Builder->>FS: rebuild affected entries
      DevCLI->>HTTP: start static server (serve dist)
      HTTP->>DevCLI: serve on auto-detected port
    end
  end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Pay attention to packages/materials/buildMaterials.mjs for: file-watching edge cases, JSON validation rules, error handling/log messages, and correctness of combined bundle format.
• Verify designer-demo/engine.config.js change integrates correctly with the new @opentiny/tiny-engine-materials export shape and that the new dependency version aligns with workspace expectations.

Poem

I nibble JSON under starlight bright,
Bundles hop, components take flight.
I watch and build, then serve with glee,
A tiny engine, tidy and free.
— the rabbit hums, sip of tea 🐇✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The PR title "feat(material): add material package" is clearly related to the changes in the pull request. The changeset includes the introduction of a new materials package with a build orchestration module (buildMaterials.mjs), integration into the engine configuration, and a new dependency addition. The title accurately captures the primary objective—adding a material package—and uses clear, conventional commit format with a specific scope ("material") rather than vague terminology. A teammate reviewing the commit history would understand this involves material-related features being added to the project.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}