Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,5 @@ When working in this repository, you MUST follow these rules:
3. **CLI**: Documentation must instruct users to use `npx @modus-ui/cli add <component>`; write the npm form in the docs and the site shows pnpm, yarn and bun tabs for it (`src/lib/install.ts`). Do NOT use `npx shadcn`, `npx react-ui-component` or the unscoped `npx modus-ui` (that npm package belongs to someone else).
4. **Registration**: Start new components with `pnpm new:component --name <slug> --category <Category>`. Register a component in exactly two places: its entry (name, title, category, dependencies, files) in `src/registry/index.ts` and its demo in `src/registry/demos.ts`. The sidebar, components index and previews are derived from these; never hand-edit lists there.
5. **Theme colors**: Tokens are bare HSL channels, so use `hsl(var(--primary))`, never `var(--primary)`. On a `<canvas>`, resolve colors through `getComputedStyle` first.
6. **React Native components**: Components in the `React Native` category are React Native (Expo), with `platform: "native"` and `dependencies: []` in the registry. Import only from `react-native`; use `Animated` and `PanResponder`, not `framer-motion`, `className` or `cn()`. Take colors through a `colors?: Partial<...>` prop with plain defaults (there are no CSS variables in React Native), and read the system setting with `AccessibilityInfo.isReduceMotionEnabled()`. Use `NATIVE_DRIVER = Platform.OS !== "web"` and `userSelect: "none"` on draggable surfaces so the docs preview works with a mouse. The demo wraps its content in `NativeStage` (`src/registry/native-stage.tsx`), which draws a phone frame around it; its `height` is the screen area between the status bar and the home indicator and is registered with `dynamic(..., { ssr: false })` in `demos.ts`.
6. **React Native components**: Components in the `React Native · …` categories (Inputs, Buttons, Navigation, Overlays, Feedback, Progress, Data) are React Native (Expo), with `platform: "native"` and `dependencies: []` in the registry. Import only from `react-native`; use `Animated` and `PanResponder`, not `framer-motion`, `className` or `cn()`. Take colors through a `colors?: Partial<...>` prop with plain defaults (there are no CSS variables in React Native), and read the system setting with `AccessibilityInfo.isReduceMotionEnabled()`. Use `NATIVE_DRIVER = Platform.OS !== "web"` and `userSelect: "none"` on draggable surfaces so the docs preview works with a mouse. The demo wraps its content in `NativeStage` (`src/registry/native-stage.tsx`), which draws a phone frame around it; its `height` is the screen area between the status bar and the home indicator and is registered with `dynamic(..., { ssr: false })` in `demos.ts`.
7. **Hooks, providers and theme tokens**: These live in the `Hooks`, `Providers` and `Theme` categories with `platform: "both"`. When React and React Native need different code, `files` lists the React file first and a `name.native.ts(x)` file second (Metro resolves it by itself), the React file starts with `"use client"`, and a demo for each goes in `demos.ts` and `src/registry/web-demos/`. When one file works on both, list just that file. They are exempt from the `colors` prop and reduced-motion rules and document an `## API` section instead of `## Props` (providers keep `## Props`).
30 changes: 21 additions & 9 deletions README.md

Large diffs are not rendered by default.

41 changes: 41 additions & 0 deletions packages/cli/src/add.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,14 @@ const catalogue = {
categories: ["Text"],
renamed: { "fuzzy-text": "blur-text" },
components: [
{
name: "use-flag",
title: "useFlag",
category: "Hooks",
platform: "both",
description: "d",
dependencies: [],
},
{
name: "blur-text",
title: "Blur Text",
Expand All @@ -30,6 +38,20 @@ const catalogue = {
};

function component(name: string) {
if (name === "use-flag") {
return {
name,
title: name,
category: "Hooks",
type: "registry:ui",
platform: "both",
dependencies: [],
files: [
{ path: "registry/use-flag.ts", content: "// react\n" },
{ path: "registry/use-flag.native.ts", content: "// react native\n" },
],
};
}
return {
name,
title: name,
Expand Down Expand Up @@ -70,6 +92,25 @@ afterEach(async () => {
await rm(dir, { recursive: true, force: true });
});

describe("add for both platforms", () => {
it("installs the React Native file in an Expo app, with no cn helper or class packages", async () => {
await project({ dependencies: { expo: "55.0.0", "react-native": "0.88.0" } });
await add(["use-flag"], { cwd: dir, run, log });
expect(await readFile(join(dir, "components/ui/use-flag.ts"), "utf8")).toBe(
"// react native\n",
);
expect(existsSync(join(dir, "lib/utils.ts"))).toBe(false);
expect(run).not.toHaveBeenCalled();
});

it("installs the React file in a web app, also without the cn helper", async () => {
await project({ dependencies: { next: "14.0.0" } });
await add(["use-flag"], { cwd: dir, run, log });
expect(await readFile(join(dir, "components/ui/use-flag.ts"), "utf8")).toBe("// react\n");
expect(existsSync(join(dir, "lib/utils.ts"))).toBe(false);
});
});

describe("add", () => {
it("resolves a renamed component to its current name", async () => {
await project();
Expand Down
31 changes: 21 additions & 10 deletions packages/cli/src/commands/add.ts
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import {
findUtilsFile,
installCommand,
installedDependencies,
isReactNativeProject,
readPackageJson,
utilsFileTarget,
} from "../project.js";
Expand Down Expand Up @@ -77,10 +78,16 @@ export async function add(names: string[], options: AddOptions): Promise<void> {
const componentsDir = options.path ? resolve(cwd, options.path) : defaultComponentsDir(cwd);
const deps = new Set<string>();
let wrote = false;
let usesCn = false;
const native = isReactNativeProject(pkg);
for (const component of components) {
const file = component.files[0];
// An item for both platforms ships a React file first and may add a `.native` one; an Expo or
// React Native app takes the `.native` file, anywhere else gets the React file.
const file =
(native && component.files.find((f) => /\.native\.tsx?$/.test(f.path))) || component.files[0];
if (!file) throw new Error(`Registry entry for ${component.name} has no files.`);
const target = join(componentsDir, `${component.name}.tsx`);
const extension = file.path.endsWith(".ts") ? ".ts" : ".tsx";
const target = join(componentsDir, `${component.name}${extension}`);
const shown = relative(cwd, target);
if (existsSync(target) && !options.overwrite) {
log(`Skipped ${shown} (already exists, pass --overwrite to replace it)`);
Expand All @@ -90,20 +97,24 @@ export async function add(names: string[], options: AddOptions): Promise<void> {
await writeFile(target, file.content);
log(`Added ${shown}`);
wrote = true;
if (!component.platform || component.platform === "web") usesCn = true;
for (const dep of component.dependencies) deps.add(dep);
}

if (!wrote) return;

// Every component imports cn from @/lib/utils, which needs clsx and tailwind-merge.
if (!findUtilsFile(cwd)) {
const utils = utilsFileTarget(cwd);
await mkdir(dirname(utils), { recursive: true });
await writeFile(utils, CN_SOURCE);
log(`Created ${relative(cwd, utils)} with the cn() helper`);
// Web components import cn from @/lib/utils, which needs clsx and tailwind-merge. React Native files
// and the hooks, providers and theme tokens use neither.
if (usesCn) {
if (!findUtilsFile(cwd)) {
const utils = utilsFileTarget(cwd);
await mkdir(dirname(utils), { recursive: true });
await writeFile(utils, CN_SOURCE);
log(`Created ${relative(cwd, utils)} with the cn() helper`);
}
deps.add("clsx");
deps.add("tailwind-merge");
}
deps.add("clsx");
deps.add("tailwind-merge");

const installed = installedDependencies(pkg);
const missing = [...deps].filter((d) => !installed.has(d)).sort();
Expand Down
6 changes: 6 additions & 0 deletions packages/cli/src/project.ts
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,12 @@ export function installedDependencies(pkg: Record<string, unknown>): Set<string>
return names;
}

/** True for an Expo or React Native app, which wants the `.native` file of an item that has one. */
export function isReactNativeProject(pkg: Record<string, unknown>): boolean {
const deps = installedDependencies(pkg);
return deps.has("react-native") || deps.has("expo");
}

export function hasSrcDir(cwd: string): boolean {
return existsSync(join(cwd, "src"));
}
Expand Down
2 changes: 2 additions & 0 deletions packages/cli/src/registry.ts
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,8 @@ export interface RegistryComponent {
title: string;
category: string;
type: string;
/** "native" is React Native only, "both" works in React and React Native, anything else is web. */
platform?: "web" | "native" | "both";
dependencies: string[];
files: { path: string; content: string }[];
}
Expand Down
6 changes: 3 additions & 3 deletions packages/mcp/src/catalogue.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ export interface CatalogueComponent {
name: string;
title: string;
category: string;
/** "native" components are React Native (Expo); everything else is a web component. */
platform?: "web" | "native";
/** "native" components are React Native (Expo), "both" work in React and React Native; everything else is web. */
platform?: "web" | "native" | "both";
description: string;
dependencies: string[];
}
Expand Down Expand Up @@ -99,7 +99,7 @@ export function fallbackMarkdown(
"",
entry.description,
"",
`Category: ${entry.category}. ${entry.platform === "native" ? "Platform: React Native (Expo). " : ""}Docs: ${origin}/components/${entry.name}`,
`Category: ${entry.category}. ${entry.platform === "native" ? "Platform: React Native (Expo). " : entry.platform === "both" ? "Platform: React and React Native. " : ""}Docs: ${origin}/components/${entry.name}`,
"",
"## Installation",
"",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/action-button.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "action-button",
"title": "Action Button",
"category": "React Native",
"category": "React Native · Buttons",
"type": "components:ui",
"platform": "native",
"added": "2026-11-03",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/action-tray.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "action-tray",
"title": "Action Tray",
"category": "React Native",
"category": "React Native · Overlays",
"type": "components:ui",
"platform": "native",
"added": "2026-11-02",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/avatar-stack.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "avatar-stack",
"title": "Avatar Stack",
"category": "React Native",
"category": "React Native · Data",
"type": "components:ui",
"platform": "native",
"added": "2026-11-02",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/battery-meter.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "battery-meter",
"title": "Battery Meter",
"category": "React Native",
"category": "React Native · Progress",
"type": "components:ui",
"platform": "native",
"added": "2026-11-03",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/bubble-tab-bar.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "bubble-tab-bar",
"title": "Bubble Tab Bar",
"category": "React Native",
"category": "React Native · Navigation",
"type": "components:ui",
"platform": "native",
"added": "2026-11-02",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/calendar-strip.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "calendar-strip",
"title": "Calendar Strip",
"category": "React Native",
"category": "React Native · Inputs",
"type": "components:ui",
"platform": "native",
"added": "2026-11-02",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/card-field.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "card-field",
"title": "Card Field",
"category": "React Native",
"category": "React Native · Inputs",
"type": "components:ui",
"platform": "native",
"added": "2026-11-03",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/cart-quantity.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "cart-quantity",
"title": "Cart Quantity",
"category": "React Native",
"category": "React Native · Inputs",
"type": "components:ui",
"platform": "native",
"added": "2026-11-03",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/chat-bubble.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "chat-bubble",
"title": "Chat Bubble",
"category": "React Native",
"category": "React Native · Data",
"type": "components:ui",
"platform": "native",
"added": "2026-11-03",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/chip-input.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "chip-input",
"title": "Chip Input",
"category": "React Native",
"category": "React Native · Inputs",
"type": "components:ui",
"platform": "native",
"added": "2026-11-02",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/choice-chips.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "choice-chips",
"title": "Choice Chips",
"category": "React Native",
"category": "React Native · Inputs",
"type": "components:ui",
"platform": "native",
"added": "2026-11-02",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/code-boxes.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "code-boxes",
"title": "Code Boxes",
"category": "React Native",
"category": "React Native · Inputs",
"type": "components:ui",
"platform": "native",
"added": "2026-11-02",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/compare-slider.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "compare-slider",
"title": "Compare Slider",
"category": "React Native",
"category": "React Native · Data",
"type": "components:ui",
"platform": "native",
"added": "2026-11-03",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/composer-bar.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "composer-bar",
"title": "Composer Bar",
"category": "React Native",
"category": "React Native · Inputs",
"type": "components:ui",
"platform": "native",
"added": "2026-11-03",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/confirm-dialog.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "confirm-dialog",
"title": "Confirm Dialog",
"category": "React Native",
"category": "React Native · Overlays",
"type": "components:ui",
"platform": "native",
"added": "2026-11-02",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/contact-index.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "contact-index",
"title": "Contact Index",
"category": "React Native",
"category": "React Native · Data",
"type": "components:ui",
"platform": "native",
"added": "2026-11-03",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/count-badge.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "count-badge",
"title": "Count Badge",
"category": "React Native",
"category": "React Native · Feedback",
"type": "components:ui",
"platform": "native",
"added": "2026-11-02",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/countdown-timer.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "countdown-timer",
"title": "Countdown Timer",
"category": "React Native",
"category": "React Native · Progress",
"type": "components:ui",
"platform": "native",
"added": "2026-11-03",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/data-table.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "data-table",
"title": "Data Table",
"category": "React Native",
"category": "React Native · Data",
"type": "components:ui",
"platform": "native",
"added": "2026-11-03",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/drag-list.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "drag-list",
"title": "Drag List",
"category": "React Native",
"category": "React Native · Data",
"type": "components:ui",
"platform": "native",
"added": "2026-11-02",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/empty-state.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "empty-state",
"title": "Empty State",
"category": "React Native",
"category": "React Native · Feedback",
"type": "components:ui",
"platform": "native",
"added": "2026-11-03",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/expand-card.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "expand-card",
"title": "Expand Card",
"category": "React Native",
"category": "React Native · Data",
"type": "components:ui",
"platform": "native",
"added": "2026-11-02",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/expand-search.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "expand-search",
"title": "Expand Search",
"category": "React Native",
"category": "React Native · Inputs",
"type": "components:ui",
"platform": "native",
"added": "2026-11-02",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/expandable-text.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "expandable-text",
"title": "Expandable Text",
"category": "React Native",
"category": "React Native · Data",
"type": "components:ui",
"platform": "native",
"added": "2026-11-03",
Expand Down
2 changes: 1 addition & 1 deletion public/registry/extended-fab.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "extended-fab",
"title": "Extended FAB",
"category": "React Native",
"category": "React Native · Buttons",
"type": "components:ui",
"platform": "native",
"added": "2026-11-03",
Expand Down
Loading
Loading