@antscorp/ui 0.1.2 → 0.1.4

package/README.md

@@ -1,6 +1,8 @@
 # @antscorp/ui
 
-React 19 views, Astryx, StyleX and the Antsomi theme through one facade.
+React >=19.2 views, Astryx, StyleX and the Antsomi theme through one facade.
+React and React DOM >=19.2 are supplied by the host as peers.
+The packaged CLI requires Node >=24.
 
 ```sh
 bun add @antscorp/ui
@@ -23,5 +25,27 @@ export function Example() {
 ```
 
 StyleX consumers select `antscorp-source` and extract their own CSS instead of importing
-`ui.css`. See the [repository README](https://bitbucket.org/git-vn/at.antsomi-ui/src/main/README.md)
+`ui.css`. See the [repository README](../../README.md)
 for source configuration, linked development and releases.
+
+## Localization
+
+The host translates kit `label`/`labels`, descriptions and errors. Astryx-owned calendar,
+clear, search and status text uses `InternationalizationProvider` from the same facade:
+
+```tsx
+import { getLocaleDirection, InternationalizationProvider } from "@antscorp/ui/astryx/i18n";
+import arSA from "@antscorp/ui/astryx/locales/ar-SA.generated.js";
+
+const locale = "ar-SA";
+const dir = getLocaleDirection(locale);
+
+// The host also sets <html dir={dir}>; this provider renders no DOM element.
+<InternationalizationProvider locale={locale} messages={{ [locale]: arSA }} dir={dir}>
+  <AntsomiTheme>{/* Views with host-translated labels. */}</AntsomiTheme>
+</InternationalizationProvider>;
+```
+
+Keep the DOM `dir` and provider direction in sync. Use `overrides` for sparse, locale-keyed
+upstream text changes; missing translations fall back to English. `DateTimeInput` defaults to
+`hourFormat="12h"`; set `hourFormat="24h"` for a 24-hour clock. No second translation layer is needed.

package/dist/atoms/AddButton.d.ts

@@ -1,18 +1,15 @@
+import { type ButtonProps } from "@astryxdesign/core/Button";
 import type { ReactNode } from "react";
 /** What `AddButton` takes. */
-export type AddButtonProps = {
-    /** What it adds, such as "Add row"; the host translates it. */
-    readonly label: string;
+export type AddButtonProps = Pick<ButtonProps, "label" | "isDisabled"> & {
     /** `ghost` by default; `secondary` for an add that needs more weight. */
     readonly variant?: "ghost" | "secondary" | undefined;
     /** The button's height, `md` by default; its plus follows it. */
     readonly size?: "sm" | "md" | undefined;
     /** `default` keeps the button's own corners; `pill` rounds them fully; the theme colours its outline. */
     readonly shape?: "default" | "pill" | undefined;
-    /** `sentence` (default) shows the label as given; `upper` in capitals, as fe-app's "+ AND". */
+    /** `sentence` (default) shows the label as given; `upper` in capitals, such as "+ AND". */
     readonly case?: "sentence" | "upper" | undefined;
-    /** Dimmed and not pressable, e.g. when a limit is reached. */
-    readonly isDisabled?: boolean | undefined;
     /** Read-only: an add is an editing affordance, so nothing is drawn. */
     readonly isReadOnly?: boolean | undefined;
     /** Called when the button is pressed. */

package/dist/atoms/Chip.d.ts

@@ -1,8 +1,7 @@
+import { type TokenProps } from "@astryxdesign/core/Token";
 import type { ReactNode } from "react";
 /** What `Chip` takes. */
-export type ChipProps = {
-    /** The chip's text; cut short with an ellipsis past `maxWidth`, and shown whole in a tooltip. */
-    readonly label: string;
+export type ChipProps = Pick<TokenProps, "label" | "isDisabled"> & {
     /** `neutral` (default) is the plain grey chip; `accent` the pale accent one; `danger` a value no longer valid. */
     readonly tone?: "neutral" | "accent" | "danger" | undefined;
     /** The chip's height, `sm` or `md` (default), as the controls beside it. */
@@ -21,8 +20,6 @@ export type ChipProps = {
      * button over its end; it stays in the tab order. Without it the button always shows after the text.
      */
     readonly isRemoveOnHover?: boolean | undefined;
-    /** Dims the chip and blocks its remove button. */
-    readonly isDisabled?: boolean | undefined;
     /** Read-only: no remove button. */
     readonly isReadOnly?: boolean | undefined;
 };

package/dist/atoms/Chip.js

@@ -77,7 +77,7 @@ var l = {
 		$$css: !0
 	},
 	accent: {
-		kWkggS: "aui1gbsizx",
+		kWkggS: "auisqkk90",
 		kMwMTN: "aui1tgivj0",
 		$$css: !0
 	},

package/dist/atoms/InfoTip.js

@@ -17,6 +17,7 @@ function a(a) {
 	let m;
 	s[5] !== c || s[6] !== p ? (m = /* @__PURE__ */ t(i, {
 		as: "span",
+		tabIndex: 0,
 		color: "accent",
 		"aria-label": c,
 		xstyle: o.info,
@@ -25,6 +26,7 @@ function a(a) {
 	let h;
 	return s[8] !== c || s[9] !== m ? (h = /* @__PURE__ */ t(r, {
 		content: c,
+		focusTrigger: "always",
 		children: m
 	}), s[8] = c, s[9] = m, s[10] = h) : h = s[10], h;
 }

package/dist/atoms/LabeledDivider.d.ts

@@ -3,7 +3,7 @@ import type { ReactNode } from "react";
 export type LabeledDividerProps = {
     /** The short word on the rule, such as "or"; it also names the separator. */
     readonly label: string;
-    /** `sentence` (default) shows the word as given; `upper` in capitals, as fe-app's "OR". */
+    /** `sentence` (default) shows the word as given; `upper` in capitals, such as "OR". */
     readonly case?: "sentence" | "upper" | undefined;
 };
 /**

package/dist/atoms/PanelSearchInput.d.ts

@@ -14,7 +14,7 @@ export type PanelSearchInputProps = {
         /** The clear button's name, such as "Clear search"; it shows only an icon. */
         readonly clear: string;
     };
-    /** Where the magnifier sits: `start` (default) or `end`, after the clear button, as fe-app's search. */
+    /** Where the magnifier sits: `start` (default) or `end`, after the clear button. */
     readonly iconPosition?: "start" | "end" | undefined;
     /** The input element, to focus it (with `useFocusLater` in a pop-over, say). */
     readonly ref?: Ref<HTMLInputElement> | undefined;

package/dist/atoms/RemoveButton.d.ts

@@ -1,12 +1,9 @@
+import { type IconButtonProps } from "@astryxdesign/core/IconButton";
 import type { ReactNode } from "react";
 /** What `RemoveButton` takes. */
-export type RemoveButtonProps = {
-    /** What goes, such as "Remove row"; the button shows only an icon, so this is its name. */
-    readonly label: string;
+export type RemoveButtonProps = Pick<IconButtonProps, "label" | "isDisabled"> & {
     /** The button's height, `md` by default. */
     readonly size?: "sm" | "md" | undefined;
-    /** Dimmed and not pressable. */
-    readonly isDisabled?: boolean | undefined;
     /** Read-only: a remove is an editing affordance, so nothing is drawn. */
     readonly isReadOnly?: boolean | undefined;
     /** Called when the button is pressed. */

package/dist/atoms/TextAction.d.ts

@@ -1,11 +1,12 @@
+import { type LinkProps } from "@astryxdesign/core/Link";
 import type { ReactNode } from "react";
 /** What `TextAction` takes. */
-export type TextActionProps = {
+export type TextActionProps = Pick<LinkProps, "isDisabled"> & {
     /** What it does, such as "Remove all"; shown in capitals by default, so pass it in normal case. */
     readonly label: string;
     /** A glyph before the text, in the text's colour, such as an Astryx `Icon` of a bin for a removal. */
     readonly icon?: ReactNode;
-    /** `upper` (default) shows the label in capitals, as fe-app's "REMOVE ALL"; `sentence` as given, as fe-app's text buttons. */
+    /** `upper` (default) shows the label in capitals, such as "REMOVE ALL"; `sentence` as given. */
     readonly case?: "upper" | "sentence" | undefined;
     /**
      * Called when it is pressed. Leave it out when a wrapper handles the presses, such as an Astryx
@@ -14,12 +15,10 @@ export type TextActionProps = {
     readonly onClick?: (() => void) | undefined;
     /** A down chevron after the text, for an action that opens a menu. */
     readonly hasChevron?: boolean | undefined;
-    /** Dimmed and not pressable. */
-    readonly isDisabled?: boolean | undefined;
 };
 /**
- * An action drawn as text alone: bold capitals in the accent, no frame, as fe-app's "REMOVE ALL"
- * and "CREATE NEW … ▾", or in sentence case with a glyph before it, as fe-app's text buttons
+ * An action drawn as text alone: bold capitals in the accent, no frame, such as "REMOVE ALL"
+ * and "CREATE NEW … ▾", or in sentence case with a glyph before it
  * (a bin, then "Remove"). An Astryx `Link` without an `href`, so a `<button>` in a link's look, with
  * a down chevron after the text when it opens a menu; still a button without `onClick`, so it can
  * be a `Popover`'s trigger. It holds no state.

package/dist/atoms/TruncatedOption.d.ts

@@ -7,7 +7,7 @@ export type TruncatedOptionProps = {
 };
 /**
  * A Selector option whose label ends in an ellipsis when it is wider than the pop-up, with the
- * whole label in a tooltip on hover, as antd's Select. Its icon and description show as the
+ * whole label in a tooltip on hover. Its icon and description show as the
  * Selector's own option's. It holds no state.
  */
 export declare function TruncatedOption({ option }: TruncatedOptionProps): ReactNode;

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 };