@mahiraltinkaya/me-ui 0.1.0

package/registry.json

@@ -0,0 +1,252 @@
+{
+  "name": "me-ui",
+  "baseTokens": [
+    "--background",
+    "--foreground",
+    "--muted",
+    "--muted-foreground",
+    "--primary",
+    "--primary-foreground",
+    "--secondary",
+    "--secondary-foreground",
+    "--border",
+    "--input",
+    "--ring",
+    "--destructive",
+    "--radius"
+  ],
+  "items": [
+    {
+      "name": "utils",
+      "title": "cn",
+      "description": "Class name merger — clsx piped through tailwind-merge.",
+      "dependencies": ["clsx", "tailwind-merge"],
+      "files": [
+        {
+          "source": "src/lib/utils.ts",
+          "path": "lib/utils.ts"
+        }
+      ]
+    },
+    {
+      "name": "brand-theme",
+      "title": "Brand Theme",
+      "description": "The --brand token the fields paint their focus, error and accent states with.",
+      "cssVars": {
+        "theme": {
+          "--color-brand": "var(--brand)"
+        },
+        "light": {
+          "--brand": "#870052"
+        }
+      }
+    },
+    {
+      "name": "field-hint",
+      "title": "Field Hint",
+      "description": "Explanatory panel anchored to a field's trailing info mark. Built on Tooltip so it never steals focus from the field that opened it.",
+      "dependencies": ["@base-ui/react", "lucide-react"],
+      "cssVars": {
+        "theme": {
+          "--color-ink": "var(--ink)"
+        },
+        "light": {
+          "--ink": "#0b1324"
+        }
+      },
+      "registryDependencies": ["utils", "brand-theme"],
+      "files": [
+        {
+          "source": "src/components/ui/field-hint.tsx",
+          "path": "components/ui/field-hint.tsx"
+        }
+      ]
+    },
+    {
+      "name": "input",
+      "title": "Input",
+      "description": "Text field with an optional leading icon and a focus-driven hint panel.",
+      "dependencies": ["@base-ui/react"],
+      "registryDependencies": ["utils", "field-hint"],
+      "files": [
+        {
+          "source": "src/components/ui/input.tsx",
+          "path": "components/ui/input.tsx"
+        }
+      ]
+    },
+    {
+      "name": "select",
+      "title": "Select",
+      "description": "Single-choice dropdown over a string list, with the same icon and hint affordances as Input.",
+      "dependencies": ["@base-ui/react", "lucide-react"],
+      "registryDependencies": ["utils", "field-hint"],
+      "files": [
+        {
+          "source": "src/components/ui/select.tsx",
+          "path": "components/ui/select.tsx"
+        }
+      ]
+    },
+    {
+      "name": "button",
+      "title": "Button",
+      "description": "Button with variant, size and shape sets built on class-variance-authority.",
+      "dependencies": ["@base-ui/react", "class-variance-authority"],
+      "registryDependencies": ["utils", "brand-theme"],
+      "cssVars": {
+        "theme": {
+          "--color-cta": "var(--cta)",
+          "--color-cta-hover": "var(--cta-hover)"
+        },
+        "light": {
+          "--cta": "#111c3a",
+          "--cta-hover": "#1c2b52"
+        }
+      },
+      "files": [
+        {
+          "source": "src/components/ui/button.tsx",
+          "path": "components/ui/button.tsx"
+        }
+      ]
+    },
+    {
+      "name": "tooltip",
+      "title": "Tooltip",
+      "description": "Tooltip primitives — provider, root, trigger and content.",
+      "dependencies": ["@base-ui/react"],
+      "registryDependencies": ["utils"],
+      "files": [
+        {
+          "source": "src/components/ui/tooltip.tsx",
+          "path": "components/ui/tooltip.tsx"
+        }
+      ]
+    },
+    {
+      "name": "stepper",
+      "title": "Stepper",
+      "description": "Progress rail for multi-step flows: a mobile progress bar plus a clickable desktop rail.",
+      "dependencies": ["next"],
+      "registryDependencies": ["utils", "brand-theme"],
+      "files": [
+        {
+          "source": "public/assets/images/breadcrumb_arrow.svg",
+          "path": "assets/breadcrumb_arrow.svg",
+          "target": "public/assets/images/breadcrumb_arrow.svg"
+        },
+        {
+          "source": "src/components/ui/stepper/index.tsx",
+          "path": "components/ui/stepper/index.tsx"
+        },
+        {
+          "source": "src/components/ui/stepper/types.ts",
+          "path": "components/ui/stepper/types.ts"
+        },
+        {
+          "source": "src/components/ui/stepper/step-divider.tsx",
+          "path": "components/ui/stepper/step-divider.tsx"
+        },
+        {
+          "source": "src/components/ui/stepper/step-indicator.tsx",
+          "path": "components/ui/stepper/step-indicator.tsx"
+        },
+        {
+          "source": "src/components/ui/stepper/step-label.tsx",
+          "path": "components/ui/stepper/step-label.tsx"
+        },
+        {
+          "source": "src/components/ui/stepper/stepper-progress.tsx",
+          "path": "components/ui/stepper/stepper-progress.tsx"
+        },
+        {
+          "source": "src/components/ui/stepper/stepper-rail.tsx",
+          "path": "components/ui/stepper/stepper-rail.tsx"
+        }
+      ]
+    },
+    {
+      "name": "stepper-provider",
+      "title": "Stepper Provider",
+      "description": "Step state behind a context — current index, next/back guards and a useStepper hook — plus the view that renders the rail and the active step.",
+      "registryDependencies": ["utils", "stepper"],
+      "files": [
+        {
+          "source": "src/components/stepper-provider.tsx",
+          "path": "components/stepper-provider.tsx"
+        },
+        {
+          "source": "src/components/stepper-view.tsx",
+          "path": "components/stepper-view.tsx"
+        }
+      ]
+    },
+    {
+      "name": "step-field",
+      "title": "Step Field",
+      "description": "Label, control and validation message. Layout only — it holds no form state.",
+      "dependencies": ["lucide-react"],
+      "registryDependencies": ["brand-theme"],
+      "files": [
+        {
+          "source": "src/components/steps/step-field.tsx",
+          "path": "components/steps/step-field.tsx"
+        }
+      ]
+    },
+    {
+      "name": "form-fields",
+      "title": "Form Fields",
+      "description": "FormInput and FormSelect bound to react-hook-form through useController, so a field's error re-renders that field alone.",
+      "dependencies": ["react-hook-form"],
+      "registryDependencies": ["input", "select", "step-field"],
+      "files": [
+        {
+          "source": "src/components/steps/form-input.tsx",
+          "path": "components/steps/form-input.tsx"
+        },
+        {
+          "source": "src/components/steps/form-select.tsx",
+          "path": "components/steps/form-select.tsx"
+        }
+      ]
+    },
+    {
+      "name": "normalize",
+      "title": "normalize",
+      "description": "Input normalisers — currently `digits`, which strips everything that is not a digit.",
+      "files": [
+        {
+          "source": "src/lib/normalize.ts",
+          "path": "lib/normalize.ts"
+        }
+      ]
+    },
+    {
+      "name": "tckn",
+      "title": "T.C. Kimlik No",
+      "description": "Validates a Turkish national identity number, check digits included — which is what stops a typo from passing as a real identity.",
+      "registryDependencies": ["normalize"],
+      "files": [
+        {
+          "source": "src/lib/tckn.ts",
+          "path": "lib/tckn.ts"
+        }
+      ]
+    },
+    {
+      "name": "quote-schema",
+      "title": "Quote Schema",
+      "description": "Zod schemas for the quote flow — TCKN, Turkish mobile number, e-mail and occupation — plus per-step field lists and form defaults.",
+      "dependencies": ["zod"],
+      "registryDependencies": ["normalize", "tckn"],
+      "files": [
+        {
+          "source": "src/lib/quote-schema.ts",
+          "path": "lib/quote-schema.ts"
+        }
+      ]
+    }
+  ]
+}

package/src/args.js

@@ -0,0 +1,47 @@
+/** Argument parsing. Hand-rolled so the package stays dependency-free. */
+
+const FLAGS = {
+  overwrite: "overwrite",
+  o: "overwrite",
+  "dry-run": "dryRun",
+  "skip-install": "skipInstall",
+  help: "help",
+  h: "help",
+  version: "version",
+  v: "version",
+};
+
+const OPTIONS = { cwd: "cwd", c: "cwd" };
+
+export function parseArgs(argv) {
+  const result = { command: undefined, items: [], cwd: process.cwd() };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (!arg.startsWith("-")) {
+      if (result.command === undefined) result.command = arg;
+      else result.items.push(arg);
+      continue;
+    }
+
+    // `--cwd=x` and `--cwd x` are both accepted.
+    const [name, inlineValue] = arg.replace(/^--?/, "").split(/=(.*)/s);
+
+    if (OPTIONS[name]) {
+      const value = inlineValue ?? argv[++index];
+      if (value === undefined) throw new Error(`--${name} needs a value.`);
+      result[OPTIONS[name]] = value;
+      continue;
+    }
+
+    if (FLAGS[name]) {
+      result[FLAGS[name]] = true;
+      continue;
+    }
+
+    throw new Error(`Unknown option "${arg}".`);
+  }
+
+  return result;
+}

package/src/commands/add.js

@@ -0,0 +1,118 @@
+/** `me-ui add <items…>` — copies items and everything they depend on. */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { applyCssVars, missingBaseTokens } from "../css.js";
+import { installDependencies, missingDependencies } from "../deps.js";
+import { cssVarsOf, manifest, npmDependenciesOf, registryDir, resolveItems } from "../manifest.js";
+import { displayPathOf, rewriteImports, targetPathOf } from "../paths.js";
+import { loadProject } from "../project.js";
+import { bullet, cyan, dim, green, heading, line, warn, yellow } from "../log.js";
+
+/** Decides, per file, between writing it, replacing it, and leaving it alone. */
+function planFiles(items, project) {
+  return items
+    .flatMap((item) => item.files ?? [])
+    .map((file) => {
+      const target = targetPathOf(file, project);
+      const source = readFileSync(join(registryDir, file.path), "utf8");
+      const contents = file.target ? source : rewriteImports(source, project);
+      const current = existsSync(target) ? readFileSync(target, "utf8") : undefined;
+
+      const action =
+        current === undefined ? "create" : current === contents ? "identical" : "conflict";
+
+      return { display: displayPathOf(file, project), target, contents, action };
+    });
+}
+
+const MARKS = {
+  create: green("+"),
+  overwrite: yellow("~"),
+  identical: dim("="),
+  conflict: yellow("!"),
+};
+
+function reportPlan(plan, overwrite) {
+  heading("Files");
+  for (const file of plan) {
+    const action = file.action === "conflict" && overwrite ? "overwrite" : file.action;
+    const note = { identical: "unchanged", conflict: "exists — pass --overwrite to replace" }[
+      action
+    ];
+    bullet(MARKS[action], file.display, note);
+  }
+}
+
+export function add({ items: names, cwd, overwrite, dryRun, skipInstall }) {
+  if (names.length === 0) {
+    throw new Error("Name at least one item, for example `me-ui add input`.");
+  }
+
+  const items = resolveItems(names);
+  const project = loadProject(cwd);
+
+  line(
+    `${cyan("me-ui")} add ${names.join(" ")}${dryRun ? dim(" (dry run)") : ""}\n` +
+      dim(`  into ${project.root}`) +
+      dim(project.usesComponentsJson ? " — using its components.json aliases" : ""),
+  );
+
+  const plan = planFiles(items, project);
+  const writable = plan.filter(
+    (file) => file.action === "create" || (file.action === "conflict" && overwrite),
+  );
+  reportPlan(plan, overwrite);
+
+  const dependencies = missingDependencies(project, npmDependenciesOf(items));
+  if (dependencies.length > 0) {
+    heading("Dependencies");
+    dependencies.forEach((name) => bullet(green("+"), name));
+  }
+
+  const cssVars = cssVarsOf(items);
+  const css = project.cssFile ? readFileSync(project.cssFile, "utf8") : undefined;
+  const styles = css === undefined ? { css, added: [] } : applyCssVars(css, cssVars);
+  if (styles.added.length > 0) {
+    heading("Styles");
+    styles.added.forEach((name) => bullet(green("+"), name));
+  }
+
+  if (dryRun) {
+    line(`\n${dim("Dry run — nothing was written.")}`);
+    return;
+  }
+
+  for (const file of writable) {
+    mkdirSync(dirname(file.target), { recursive: true });
+    writeFileSync(file.target, file.contents);
+  }
+
+  if (styles.added.length > 0) writeFileSync(project.cssFile, styles.css);
+
+  if (dependencies.length > 0 && !skipInstall) {
+    line("");
+    installDependencies(project, dependencies);
+  }
+
+  line(`\n${green("Done.")} ${writable.length} file(s) written.`);
+
+  if (!project.cssFile && Object.keys(cssVars.light).length > 0) {
+    warn("No stylesheet found — add the design tokens by hand:");
+    Object.entries(cssVars.light).forEach(([name, value]) => bullet(" ", `${name}: ${value};`));
+  }
+
+  const absent = css === undefined ? [] : missingBaseTokens(css, manifest.baseTokens);
+  if (absent.length > 0) {
+    warn(
+      `These components also style against tokens this project does not define: ${absent.join(", ")}. ` +
+        "They come from a shadcn base theme — run `npx shadcn@latest init` if the components look unstyled.",
+    );
+  }
+
+  if (dependencies.length > 0 && skipInstall) {
+    warn(`Skipped install. Add these yourself: ${dependencies.join(" ")}`);
+  }
+}

package/src/commands/list.js

@@ -0,0 +1,20 @@
+/** `me-ui list` — the catalogue, with what each item drags in behind it. */
+
+import { manifest } from "../manifest.js";
+import { bold, cyan, dim, line } from "../log.js";
+
+export function list() {
+  line(`\n${bold("Items")} ${dim("— me-ui add <name…>")}\n`);
+
+  const width = Math.max(...manifest.items.map((item) => item.name.length));
+
+  for (const item of manifest.items) {
+    const dependencies = item.registryDependencies ?? [];
+    line(`  ${cyan(item.name.padEnd(width))}  ${item.description}`);
+    if (dependencies.length > 0) {
+      line(`  ${" ".repeat(width)}  ${dim(`also installs: ${dependencies.join(", ")}`)}`);
+    }
+  }
+
+  line("");
+}

package/src/css.js

@@ -0,0 +1,80 @@
+/**
+ * Writes design tokens into the target project's stylesheet.
+ *
+ * Only missing declarations are added — an existing `--brand` is left alone, so
+ * a project that has already retuned the colour keeps its value across upgrades.
+ */
+
+const BLOCKS = [
+  { scope: "theme", selector: "@theme inline" },
+  { scope: "light", selector: ":root" },
+];
+
+/** Body of `selector { … }`, located by counting braces so nested rules survive. */
+function findBlock(css, selector) {
+  const opening = new RegExp(
+    `(^|})\\s*${selector.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*{`,
+    "m",
+  );
+  const match = opening.exec(css);
+  if (!match) return undefined;
+
+  const start = match.index + match[0].length;
+  let depth = 1;
+  let index = start;
+
+  while (index < css.length && depth > 0) {
+    if (css[index] === "{") depth += 1;
+    if (css[index] === "}") depth -= 1;
+    index += 1;
+  }
+
+  return { start, end: index - 1 };
+}
+
+function indentationOf(body) {
+  const match = /\n([ \t]+)\S/.exec(body);
+  return match ? match[1] : "  ";
+}
+
+function addToBlock(css, block, declarations) {
+  const body = css.slice(block.start, block.end);
+  const indent = indentationOf(body);
+  const addition = declarations.map(([name, value]) => `${indent}${name}: ${value};`).join("\n");
+  const separator = body.trimEnd().endsWith(";") || body.trim() === "" ? "" : "\n";
+  return `${css.slice(0, block.end).trimEnd()}\n${separator}${addition}\n${css.slice(block.end)}`;
+}
+
+function appendBlock(css, selector, declarations) {
+  const body = declarations.map(([name, value]) => `  ${name}: ${value};`).join("\n");
+  return `${css.trimEnd()}\n\n${selector} {\n${body}\n}\n`;
+}
+
+/** Returns the stylesheet with every variable applied, plus the names it added. */
+export function applyCssVars(css, cssVars) {
+  const added = [];
+  let output = css;
+
+  for (const { scope, selector } of BLOCKS) {
+    const wanted = Object.entries(cssVars[scope] ?? {});
+    if (wanted.length === 0) continue;
+
+    const block = findBlock(output, selector);
+    const declared = block ? output.slice(block.start, block.end) : "";
+    const missing = wanted.filter(
+      ([name]) => !new RegExp(`(^|[;{\\s])${name}\\s*:`).test(declared),
+    );
+    if (missing.length === 0) continue;
+
+    output = block ? addToBlock(output, block, missing) : appendBlock(output, selector, missing);
+
+    added.push(...missing.map(([name]) => `${selector} ${name}`));
+  }
+
+  return { css: output, added };
+}
+
+/** Base tokens the components style against but do not themselves define. */
+export function missingBaseTokens(css, tokens) {
+  return tokens.filter((token) => !new RegExp(`(^|[;{\\s])${token}\\s*:`).test(css));
+}

package/src/deps.js

@@ -0,0 +1,52 @@
+/** npm dependency detection and installation for the target project. */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const MANAGERS = [
+  { lockfile: "bun.lock", command: "bun", verb: "add" },
+  { lockfile: "bun.lockb", command: "bun", verb: "add" },
+  { lockfile: "pnpm-lock.yaml", command: "pnpm", verb: "add" },
+  { lockfile: "yarn.lock", command: "yarn", verb: "add" },
+  { lockfile: "package-lock.json", command: "npm", verb: "install" },
+];
+
+const NPM = { command: "npm", verb: "install" };
+
+// The npm package-name grammar. Names are interpolated into a shell string
+// below, so they are checked against this first: today they only ever come
+// from this package's own registry.json, but that file is data, and data can
+// be edited by someone who does not know it reaches a shell.
+const SAFE_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+
+export function detectPackageManager(root) {
+  return MANAGERS.find(({ lockfile }) => existsSync(join(root, lockfile))) ?? NPM;
+}
+
+export function missingDependencies(project, dependencies) {
+  return dependencies.filter((name) => !(name in project.installedDependencies));
+}
+
+export function installDependencies(project, dependencies) {
+  const unsafe = dependencies.filter((name) => !SAFE_NAME.test(name));
+  if (unsafe.length > 0) {
+    throw new Error(`Refusing to install unexpected package name(s): ${unsafe.join(", ")}`);
+  }
+
+  const manager = detectPackageManager(project.root);
+  const invocation = `${manager.command} ${manager.verb} ${dependencies.join(" ")}`;
+
+  // Passed as one string rather than command + args: every package manager is a
+  // `.cmd` shim on Windows, which Node refuses to spawn without a shell, and an
+  // args array combined with `shell` is deprecated. The names are validated above.
+  const result = spawnSync(invocation, { cwd: project.root, stdio: "inherit", shell: true });
+
+  if (result.status !== 0) {
+    throw new Error(
+      `\`${invocation}\` failed. Install the packages yourself, or re-run with --skip-install.`,
+    );
+  }
+
+  return manager.command;
+}

package/src/jsonc.js

@@ -0,0 +1,44 @@
+/**
+ * Minimal JSON-with-comments reader, for `tsconfig.json` — which is routinely
+ * written with comments and trailing commas that `JSON.parse` rejects.
+ *
+ * Comments are stripped by scanning rather than by regex, so a `//` or `/*`
+ * sitting inside a string literal (a path, a URL) is left alone.
+ */
+
+export function parseJsonc(text) {
+  let output = "";
+  let index = 0;
+
+  while (index < text.length) {
+    const char = text[index];
+
+    if (char === '"') {
+      const start = index;
+      index += 1;
+      while (index < text.length && text[index] !== '"') {
+        index += text[index] === "\\" ? 2 : 1;
+      }
+      index += 1;
+      output += text.slice(start, index);
+      continue;
+    }
+
+    if (char === "/" && text[index + 1] === "/") {
+      while (index < text.length && text[index] !== "\n") index += 1;
+      continue;
+    }
+
+    if (char === "/" && text[index + 1] === "*") {
+      index += 2;
+      while (index < text.length && !(text[index] === "*" && text[index + 1] === "/")) index += 1;
+      index += 2;
+      continue;
+    }
+
+    output += char;
+    index += 1;
+  }
+
+  return JSON.parse(output.replace(/,(\s*[}\]])/g, "$1"));
+}

package/src/log.js

@@ -0,0 +1,32 @@
+/** Terminal output. Colour is dropped when stdout is piped or NO_COLOR is set. */
+
+const ESC = String.fromCharCode(27);
+const enabled = process.stdout.isTTY && !process.env.NO_COLOR;
+const paint = (code) => (text) => (enabled ? `${ESC}[${code}m${text}${ESC}[0m` : String(text));
+
+export const bold = paint(1);
+export const dim = paint(2);
+export const red = paint(31);
+export const green = paint(32);
+export const yellow = paint(33);
+export const cyan = paint(36);
+
+export function line(text = "") {
+  console.log(text);
+}
+
+export function heading(text) {
+  console.log(`\n${bold(text)}`);
+}
+
+export function bullet(mark, text, note) {
+  console.log(`  ${mark} ${text}${note ? ` ${dim(note)}` : ""}`);
+}
+
+export function warn(text) {
+  console.warn(`${yellow("warning")} ${text}`);
+}
+
+export function fail(text) {
+  console.error(`${red("error")} ${text}`);
+}