@antscorp/ui 0.1.2 → 0.1.3

package/dist/cli.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+// src/cli/main.ts
+import { readFileSync } from "node:fs";
+
+// src/cli/catalog.ts
+var record = (value) => typeof value === "object" && value !== null;
+var texts = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
+var objects = (value, check) => Array.isArray(value) && value.every((item) => record(item) && check(item));
+var optional = (value, check) => value === undefined || check(value);
+var text = (value) => typeof value === "string";
+function component(value) {
+  return ["name", "level", "category", "import", "description", "usage", "primaryExample"].every((key) => text(value[key])) && texts(value["keywords"]) && objects(value["bestPractices"], (item) => typeof item["guidance"] === "boolean" && text(item["description"])) && optional(value["anatomy"], (items) => objects(items, (item) => text(item["name"]) && typeof item["required"] === "boolean" && text(item["description"]))) && optional(value["accessibility"], texts) && optional(value["related"], (items) => objects(items, (item) => text(item["name"]) && text(item["when"]))) && objects(value["props"], (item) => text(item["path"]) && text(item["type"]) && typeof item["required"] === "boolean" && optional(item["requiredWhenParent"], (flag) => flag === true) && optional(item["default"], text) && text(item["description"])) && objects(value["examples"], (item) => ["name", "description", "source", "file"].every((key) => text(item[key])));
+}
+function isCatalog(value) {
+  return record(value) && value["schemaVersion"] === 1 && text(value["package"]) && text(value["version"]) && objects(value["components"], component);
+}
+function parseCatalog(source) {
+  const value = JSON.parse(source);
+  if (!isCatalog(value))
+    throw new Error("Invalid component catalog (expected schemaVersion 1). Reinstall @antscorp/ui.");
+  return value;
+}
+
+// src/cli/run.ts
+import { parseArgs } from "node:util";
+
+// src/cli/format.ts
+var nextCommand = (name) => `bunx @antscorp/ui component ${name}`;
+var line = (text) => text.replaceAll(/\s+/gu, " ").trim();
+var propsFor = (view) => ({
+  requiredProps: view.props.filter((prop) => prop.required),
+  keyProps: view.props.filter((prop) => !prop.required && (!prop.path.includes(".") || prop.path.startsWith("labels.")))
+});
+var denseData = (catalog, view) => {
+  const props = propsFor(view);
+  const fact = (prop) => ({
+    path: prop.path,
+    type: prop.required ? prop.type : prop.type.replace(/ \| undefined$/u, ""),
+    description: line(prop.description),
+    default: prop.default,
+    requiredWhenParent: prop.requiredWhenParent
+  });
+  return {
+    name: view.name,
+    package: catalog.package,
+    version: catalog.version,
+    category: view.category,
+    import: view.import,
+    usage: line(view.usage),
+    related: view.related,
+    requiredProps: props.requiredProps.map(fact),
+    bestPractices: view.bestPractices,
+    keyProps: props.keyProps.map(fact),
+    primaryExample: view.primaryExample,
+    example: `${nextCommand(view.name)} --example ${view.primaryExample}`,
+    more: [
+      `${nextCommand(view.name)} --full`,
+      "bunx @antscorp/ui search <query>",
+      "bunx @antscorp/ui list"
+    ]
+  };
+};
+function propLine(prop) {
+  const parent = prop.path.slice(0, prop.path.lastIndexOf("."));
+  const state = prop.required ? "required" : prop.requiredWhenParent === true ? `required when ${parent} is set` : "optional";
+  return `- ${prop.path}: ${line(prop.type)} (${state}${prop.default === undefined ? "" : `; default: ${prop.default}`}) — ${line(prop.description)}`;
+}
+function keyPropLines(props) {
+  return props.flatMap((prop, index) => {
+    if (!prop.path.startsWith("labels."))
+      return [propLine(prop)];
+    return [
+      ...props[index - 1]?.path.startsWith("labels") === true ? [] : ["- labels fields (see required props):"],
+      `  ${propLine(prop)}`
+    ];
+  });
+}
+function formatComponent(catalog, view, full) {
+  const { requiredProps: required, keyProps } = propsFor(view);
+  return [
+    `${view.name} — ${catalog.package} v${catalog.version} — ${view.category}`,
+    view.import,
+    `Use: ${line(view.usage)}`,
+    ...view.related === undefined ? [] : ["Alternatives:", ...view.related.map((item) => `- ${item.name}: ${line(item.when)}`)],
+    "Required props:",
+    ...required.length === 0 ? ["(none)"] : required.map(propLine),
+    "Rules:",
+    ...view.bestPractices.map((item) => `- ${item.guidance ? "Do" : "Don't"}: ${line(item.description)}`),
+    full ? "All props:" : "Key props (nested labels follow their parent):",
+    ...full ? view.props.map(propLine) : keyPropLines(keyProps),
+    ...full && view.anatomy !== undefined ? [
+      "Anatomy:",
+      ...view.anatomy.map((item) => `- ${item.name} (${item.required ? "required" : "optional"}): ${line(item.description)}`)
+    ] : [],
+    ...full && view.accessibility !== undefined ? ["Accessibility:", ...view.accessibility.map((item) => `- ${line(item)}`)] : [],
+    `Primary example: ${view.primaryExample}`,
+    `Example: ${nextCommand(view.name)} --example ${view.primaryExample}`,
+    ...full ? ["Examples:", ...view.examples.map((item) => `- ${item.name}: ${line(item.description)}`)] : [],
+    `more: ${nextCommand(view.name)} --full`,
+    "more: bunx @antscorp/ui search <query> | bunx @antscorp/ui list"
+  ].join(`
+`);
+}
+function exampleData(view, name) {
+  const example = view.examples.find((item) => item.name.toLowerCase() === name.toLowerCase());
+  if (example === undefined)
+    throw new Error(`Unknown example ${name} for ${view.name}. Examples: ${view.examples.map((item) => item.name).join(", ")}`);
+  return {
+    ...example,
+    notice: "Storybook source. This declaration requires the story module's imports, data and metadata; it is not a standalone consumer example."
+  };
+}
+function search(catalog, query) {
+  const needle = query.toLowerCase().trim();
+  const terms = needle.split(/\s+/u);
+  return catalog.components.map((view) => {
+    const name = view.name.toLowerCase();
+    const score = name === needle ? 1e5 : terms.reduce((total, term) => total + (name.includes(term) ? 1000 : view.keywords.some((word) => word.toLowerCase().includes(term)) ? 100 : view.category.toLowerCase().includes(term) ? 10 : view.usage.toLowerCase().includes(term) ? 1 : 0), 0);
+    return { view, score };
+  }).filter((item) => item.score > 0).toSorted((left, right) => right.score - left.score || left.view.name.localeCompare(right.view.name, "en")).slice(0, 5).map(({ view }) => ({
+    name: view.name,
+    category: view.category,
+    description: view.description,
+    next: nextCommand(view.name)
+  }));
+}
+function suggestions(catalog, name) {
+  function distance(candidate) {
+    let row = Array.from({ length: candidate.length + 1 }, (_, index) => index);
+    for (const [i, char] of name.toLowerCase().split("").entries()) {
+      const next = [i + 1];
+      for (const [j, other] of candidate.toLowerCase().split("").entries())
+        next.push(Math.min((next[j] ?? 0) + 1, (row[j + 1] ?? 0) + 1, (row[j] ?? 0) + Number(char !== other)));
+      row = next;
+    }
+    return row.at(-1) ?? 0;
+  }
+  return catalog.components.map((view) => ({ name: view.name, distance: distance(view.name) })).toSorted((left, right) => left.distance - right.distance || left.name.localeCompare(right.name, "en")).slice(0, 3).map((view) => view.name);
+}
+
+// src/cli/run.ts
+var USAGE = `Usage: bunx @antscorp/ui <command> [--json]
+  component <Name> [--full | --example <Story>]
+  search <query>    Up to five ranked views, with the next command
+  list             Every view: name | category | description
+  --help           Show this help`;
+function componentOutput(catalog, names, full, exampleName) {
+  const [name] = names;
+  if (name === undefined || names.length !== 1)
+    throw new Error("component requires one view name.");
+  if (full && exampleName !== undefined)
+    throw new Error("Choose --full or --example.");
+  const view = catalog.components.find((item) => item.name.toLowerCase() === name.toLowerCase());
+  if (view === undefined)
+    throw new Error(`Unknown view ${name}. Close names: ${suggestions(catalog, name).join(", ")}`);
+  if (exampleName === undefined)
+    return {
+      data: full ? { package: catalog.package, version: catalog.version, ...view } : denseData(catalog, view),
+      text: formatComponent(catalog, view, full)
+    };
+  const example = exampleData(view, exampleName);
+  return {
+    data: example,
+    text: `${view.name} — ${example.name}
+${example.description}
+${example.file}
+${example.notice}
+
+${example.source}`
+  };
+}
+function searchOutput(catalog, words) {
+  const query = words.join(" ").trim();
+  if (query.length === 0)
+    throw new Error("search requires a query.");
+  const results = search(catalog, query);
+  return {
+    data: results,
+    text: results.length === 0 ? `No matches for ${JSON.stringify(query)}.` : results.map((view) => `${view.name} | ${view.category} | ${view.description}
+next: ${view.next}`).join(`
+
+`)
+  };
+}
+function run(catalog, args) {
+  let json = false;
+  try {
+    const { values, positionals } = parseArgs({
+      args: [...args],
+      allowPositionals: true,
+      options: {
+        full: { type: "boolean" },
+        example: { type: "string" },
+        json: { type: "boolean" },
+        help: { type: "boolean", short: "h" }
+      }
+    });
+    json = values.json === true;
+    const [command, ...rest] = positionals;
+    const success = (data, formatted) => ({
+      code: 0,
+      stdout: json ? JSON.stringify(data) : formatted,
+      stderr: ""
+    });
+    if (values.help === true || command === undefined)
+      return success({ usage: USAGE }, USAGE);
+    if (command !== "component" && (values.full === true || values.example !== undefined))
+      throw new Error("--full and --example apply only to component.");
+    if (command === "list") {
+      if (rest.length > 0)
+        throw new Error("list takes no arguments.");
+      const views = catalog.components.map((view) => ({
+        name: view.name,
+        category: view.category,
+        description: view.description
+      }));
+      return success(views, views.map((view) => `${view.name} | ${view.category} | ${view.description}`).join(`
+`));
+    }
+    if (command === "search") {
+      const output = searchOutput(catalog, rest);
+      return success(output.data, output.text);
+    }
+    if (command !== "component")
+      throw new Error(`Unknown command ${command}.
+${USAGE}`);
+    const output = componentOutput(catalog, rest, values.full === true, values.example);
+    return success(output.data, output.text);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { code: 1, stdout: "", stderr: json ? JSON.stringify({ error: message }) : message };
+  }
+}
+
+// src/cli/main.ts
+try {
+  const catalog = parseCatalog(readFileSync(new URL("./docs.json", import.meta.url), "utf8"));
+  const result = run(catalog, process.argv.slice(2));
+  if (result.stdout.length > 0)
+    console.log(result.stdout);
+  if (result.stderr.length > 0)
+    console.error(result.stderr);
+  process.exitCode = result.code;
+} catch (error) {
+  console.error(`Cannot read component catalog: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+}

package/dist/doc/schema.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+/** Structured guidance beside a view; its props and examples come from TypeScript and stories. */
+export declare const componentDocSchema: z.ZodObject<{
+    category: z.ZodEnum<{
+        "Data display": "Data display";
+        Feedback: "Feedback";
+        Inputs: "Inputs";
+        Layout: "Layout";
+        Overlays: "Overlays";
+        Selection: "Selection";
+        Theme: "Theme";
+    }>;
+    keywords: z.ZodArray<z.ZodString>;
+    related: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        when: z.ZodString;
+    }, z.core.$strip>>>;
+    example: z.ZodOptional<z.ZodString>;
+    usage: z.ZodObject<{
+        description: z.ZodString;
+        bestPractices: z.ZodArray<z.ZodObject<{
+            guidance: z.ZodBoolean;
+            description: z.ZodString;
+        }, z.core.$strip>>;
+        anatomy: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            required: z.ZodBoolean;
+            description: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+    accessibility: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/** Authoring contract for a view's `<View>.doc.ts` export. */
+export type ComponentDoc = z.input<typeof componentDocSchema>;

package/dist/doc/schema.js

@@ -0,0 +1,33 @@
+import { z as e } from "zod";
+// src/doc/schema.ts
+var t = e.string().trim().min(1), n = e.object({
+	category: e.enum([
+		"Inputs",
+		"Selection",
+		"Feedback",
+		"Layout",
+		"Data display",
+		"Overlays",
+		"Theme"
+	]).describe("The view's purpose: Inputs edits values; Selection chooses options; Feedback communicates status; Layout arranges content; Data display presents values; Overlays shows dialogs or panels; Theme provides visual tokens and icons."),
+	keywords: e.array(t).min(3).describe("At least three search terms for the view."),
+	related: e.array(e.object({
+		name: t.describe("A kit view or Astryx facade module, such as astryx/Badge."),
+		when: t.describe("When to choose this alternative.")
+	})).min(1).optional().describe("Alternatives, validated against public views and facade modules during docs generation."),
+	example: t.optional().describe("The existing story export shown first, validated during docs generation."),
+	usage: e.object({
+		description: t.describe("When and how to use the view."),
+		bestPractices: e.array(e.object({
+			guidance: e.boolean().describe("True for a recommended practice; false for a practice to avoid."),
+			description: t.describe("The practice and its reason.")
+		})).min(2).refine((e) => e.some((e) => e.guidance) && e.some((e) => !e.guidance), "Include a recommended practice and a practice to avoid.").describe("Recommended practices and practices to avoid."),
+		anatomy: e.array(e.object({
+			name: t.describe("The part's name."),
+			required: e.boolean().describe("Whether this part is always present."),
+			description: t.describe("The part's purpose and the condition when it appears.")
+		})).min(1).optional().describe("The view's visible and interactive parts.")
+	}).describe("Usage, best practices and optional anatomy."),
+	accessibility: e.array(t).min(1).optional().describe("Accessible naming and interaction guidance.")
+});
+export { n as componentDocSchema };