@antscorp/ui 0.1.2 → 0.1.3

package/dist/organisms/HourOfDayRow.doc.d.ts

@@ -0,0 +1,25 @@
+/** Usage guidance for HourOfDayRow. */
+export declare const doc: {
+    category: "Selection";
+    keywords: string[];
+    usage: {
+        description: string;
+        bestPractices: ({
+            guidance: true;
+            description: string;
+        } | {
+            guidance: false;
+            description: string;
+        })[];
+        anatomy: ({
+            name: string;
+            required: true;
+            description: string;
+        } | {
+            name: string;
+            required: false;
+            description: string;
+        })[];
+    };
+    accessibility: string[];
+};

package/dist/organisms/HourOfWeekGrid.doc.d.ts

@@ -0,0 +1,25 @@
+/** Usage guidance for HourOfWeekGrid. */
+export declare const doc: {
+    category: "Selection";
+    keywords: string[];
+    usage: {
+        description: string;
+        bestPractices: ({
+            guidance: true;
+            description: string;
+        } | {
+            guidance: false;
+            description: string;
+        })[];
+        anatomy: ({
+            name: string;
+            required: true;
+            description: string;
+        } | {
+            name: string;
+            required: false;
+            description: string;
+        })[];
+    };
+    accessibility: string[];
+};

package/dist/organisms/RepeatableList.doc.d.ts

@@ -0,0 +1,21 @@
+/** Usage guidance for RepeatableList. */
+export declare const doc: {
+    category: "Inputs";
+    keywords: string[];
+    usage: {
+        description: string;
+        bestPractices: ({
+            guidance: true;
+            description: string;
+        } | {
+            guidance: false;
+            description: string;
+        })[];
+        anatomy: {
+            name: string;
+            required: false;
+            description: string;
+        }[];
+    };
+    accessibility: string[];
+};

package/dist/organisms/ResizableDrawer.doc.d.ts

@@ -0,0 +1,25 @@
+/** Usage guidance for ResizableDrawer. */
+export declare const doc: {
+    category: "Overlays";
+    keywords: string[];
+    usage: {
+        description: string;
+        bestPractices: ({
+            guidance: true;
+            description: string;
+        } | {
+            guidance: false;
+            description: string;
+        })[];
+        anatomy: ({
+            name: string;
+            required: true;
+            description: string;
+        } | {
+            name: string;
+            required: false;
+            description: string;
+        })[];
+    };
+    accessibility: string[];
+};

package/dist/organisms/RuleGroups.d.ts

@@ -47,11 +47,11 @@ export type RuleGroupsProps<R> = {
     readonly isReadOnly?: boolean | undefined;
 };
 /**
- * Rules in groups, as fe-app's attribute filter: each rule a card with an accent stripe, a title
+ * Rules in groups: each rule a card with an accent stripe, a title
  * and a close button; the word "and" under each card but a group's last, and a pill button adding
  * a rule at the end of the group; a dashed divider with "or" between groups, and a pill button
- * adding a group after the last; each word in capitals, as fe-app's. Unlike a list's add, an add at its limit (`maxRules`,
- * `maxGroups`) is gone, as fe-app's. The only rule left has no close button, so the groups are
+ * adding a group after the last; each word in capitals. Unlike a list's add, an add at its limit (`maxRules`,
+ * `maxGroups`) is hidden. The only rule left has no close button, so the groups are
  * never emptied from here; with no group at all only the button adding one shows. It holds no
  * state.
  */

package/dist/organisms/RuleGroups.doc.d.ts

@@ -0,0 +1,21 @@
+/** Usage guidance for RuleGroups. */
+export declare const doc: {
+    category: "Inputs";
+    keywords: string[];
+    usage: {
+        description: string;
+        bestPractices: ({
+            guidance: true;
+            description: string;
+        } | {
+            guidance: false;
+            description: string;
+        })[];
+        anatomy: {
+            name: string;
+            required: false;
+            description: string;
+        }[];
+    };
+    accessibility: string[];
+};

package/dist/organisms/RuleList.doc.d.ts

@@ -0,0 +1,25 @@
+/** Usage guidance for RuleList. */
+export declare const doc: {
+    category: "Inputs";
+    keywords: string[];
+    usage: {
+        description: string;
+        bestPractices: ({
+            guidance: true;
+            description: string;
+        } | {
+            guidance: false;
+            description: string;
+        })[];
+        anatomy: ({
+            name: string;
+            required: true;
+            description: string;
+        } | {
+            name: string;
+            required: false;
+            description: string;
+        })[];
+    };
+    accessibility: string[];
+};

package/dist/organisms/SearchableGroupedList.d.ts

@@ -50,7 +50,7 @@ export type SearchableGroupedListProps<I> = {
     /**
      * Caps the height, the groups scrolling under the search box, in a pop-over say; with no
      * `maxHeight` it fills its parent's height, in a side panel say. The list then pads its own edges,
-     * so the search row (its magnifier at the end, as fe-app's) and the rule under it reach the
+     * so the search row (its magnifier at the end) and the rule under it reach the
      * edges of a flush (unpadded) surface, and so does the scrollbar.
      */
     readonly scroll?: {

package/dist/organisms/SearchableGroupedList.doc.d.ts

@@ -0,0 +1,25 @@
+/** Usage guidance for SearchableGroupedList. */
+export declare const doc: {
+    category: "Selection";
+    keywords: string[];
+    usage: {
+        description: string;
+        bestPractices: ({
+            guidance: true;
+            description: string;
+        } | {
+            guidance: false;
+            description: string;
+        })[];
+        anatomy: ({
+            name: string;
+            required: true;
+            description: string;
+        } | {
+            name: string;
+            required: false;
+            description: string;
+        })[];
+    };
+    accessibility: string[];
+};

package/dist/organisms/TokenPickerDialog.doc.d.ts

@@ -0,0 +1,21 @@
+/** Usage guidance for TokenPickerDialog. */
+export declare const doc: {
+    category: "Overlays";
+    keywords: string[];
+    usage: {
+        description: string;
+        bestPractices: ({
+            guidance: true;
+            description: string;
+        } | {
+            guidance: false;
+            description: string;
+        })[];
+        anatomy: {
+            name: string;
+            required: true;
+            description: string;
+        }[];
+    };
+    accessibility: string[];
+};

package/dist/organisms/TransferPicker.d.ts

@@ -117,7 +117,7 @@ export type TransferPickerProps<V extends string> = Pick<LoadMoreOptions, "onLoa
     readonly error?: string | undefined;
 };
 /**
- * Picks options in two columns of one frame, as fe-app's target selection: a header strip with
+ * Picks options in two columns of one frame: a header strip with
  * the search (and the host's controls) over the options to tick, and the host's controls with
  * "Remove all" over the picked ones in framed rows with a remove button. Searching matches every
  * word, in any case; it stays cheap for thousands of options, and a new search scrolls the

package/dist/organisms/TransferPicker.doc.d.ts

@@ -0,0 +1,29 @@
+/** Usage guidance for TransferPicker. */
+export declare const doc: {
+    category: "Selection";
+    keywords: string[];
+    related: {
+        name: string;
+        when: string;
+    }[];
+    usage: {
+        description: string;
+        bestPractices: ({
+            guidance: true;
+            description: string;
+        } | {
+            guidance: false;
+            description: string;
+        })[];
+        anatomy: ({
+            name: string;
+            required: true;
+            description: string;
+        } | {
+            name: string;
+            required: false;
+            description: string;
+        })[];
+    };
+    accessibility: string[];
+};

package/dist/organisms/TreeSearchPanel.doc.d.ts

@@ -0,0 +1,25 @@
+/** Usage guidance for TreeSearchPanel. */
+export declare const doc: {
+    category: "Selection";
+    keywords: string[];
+    usage: {
+        description: string;
+        bestPractices: ({
+            guidance: true;
+            description: string;
+        } | {
+            guidance: false;
+            description: string;
+        })[];
+        anatomy: ({
+            name: string;
+            required: true;
+            description: string;
+        } | {
+            name: string;
+            required: false;
+            description: string;
+        })[];
+    };
+    accessibility: string[];
+};

package/dist/organisms/TreeSelect.d.ts

@@ -62,7 +62,7 @@ export type TreeSelectProps = Pick<LoadMoreOptions, "onLoadMore" | "hasMore" | "
     readonly isLoading?: boolean | undefined;
     /** The trigger's width, in pixels or any CSS length such as `"100%"`; as wide as its content without it. */
     readonly width?: number | string | undefined;
-    /** The trigger's size, `md` by default (30px, as fe-app's controls). */
+    /** The trigger's size, `md` by default (the theme's 30px control height). */
     readonly size?: "sm" | "md" | undefined;
     /** Dims the trigger and blocks it. */
     readonly isDisabled?: boolean | undefined;
@@ -78,8 +78,8 @@ export type TreeSelectProps = Pick<LoadMoreOptions, "onLoadMore" | "hasMore" | "
     readonly startAddon?: ReactNode;
 };
 /**
- * A Selector-like trigger opening a popover with a search box over a two-level tree, as fe-app's
- * `UISelectCondition use="tree"`: a group row (its chevron at the end) only opens and closes, a
+ * A Selector-like trigger opening a popover with a search box over a two-level tree:
+ * a group row (its chevron at the end) only opens and closes, a
  * leaf is picked and closes the popover, a disabled row is not picked. The search keeps a leaf
  * whose label matches and a group whose label or a child's matches, with only its matching
  * children, every group open; with `onSearchChange` the host searches instead. With

package/dist/organisms/TreeSelect.doc.d.ts

@@ -0,0 +1,29 @@
+/** Usage guidance for TreeSelect. */
+export declare const doc: {
+    category: "Selection";
+    keywords: string[];
+    related: {
+        name: string;
+        when: string;
+    }[];
+    usage: {
+        description: string;
+        bestPractices: ({
+            guidance: true;
+            description: string;
+        } | {
+            guidance: false;
+            description: string;
+        })[];
+        anatomy: ({
+            name: string;
+            required: true;
+            description: string;
+        } | {
+            name: string;
+            required: false;
+            description: string;
+        })[];
+    };
+    accessibility: string[];
+};

package/dist/theme/AntsomiTheme.doc.d.ts

@@ -0,0 +1,15 @@
+/** Usage guidance for AntsomiTheme. */
+export declare const doc: {
+    category: "Theme";
+    keywords: string[];
+    usage: {
+        description: string;
+        bestPractices: ({
+            guidance: true;
+            description: string;
+        } | {
+            guidance: false;
+            description: string;
+        })[];
+    };
+};

package/dist/theme/AntsomiTheme.doc.js

@@ -0,0 +1,22 @@
+// src/theme/AntsomiTheme.doc.ts
+var e = {
+	category: "Theme",
+	keywords: [
+		"theme",
+		"provider",
+		"tokens",
+		"icons",
+		"mode"
+	],
+	usage: {
+		description: "Apply the Antsomi base theme to a subtree and forward Astryx's light, dark or system mode. Extend antsomiTheme with defineTheme and pass the result through theme for a scoped override.",
+		bestPractices: [{
+			guidance: !0,
+			description: "Import @antscorp/ui/theme.css separately and load Roboto in the host; nest providers when an override should affect only a subtree."
+		}, {
+			guidance: !1,
+			description: "Do not expect the provider to load CSS or fonts, or replace theme tokens with hard-coded colors in consuming views."
+		}]
+	}
+};
+export { e as doc };

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "@antscorp/ui",
-  "version": "0.1.2",
-  "description": "Generic UI kit: atoms, molecules and organisms over Astryx, with no MarketingHub words.",
+  "version": "0.1.3",
+  "description": "Generic UI kit: atoms, molecules and organisms over Astryx.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://bitbucket.org/git-vn/at.antsomi-ui.git",
     "directory": "packages/ui"
   },
+  "bin": {
+    "antscorp-ui": "./dist/cli.js"
+  },
   "files": [
     "dist",
     "src",
+    "!src/cli/**",
     "!src/**/*.test.*",
     "!src/**/*.stories.*",
     "!src/**/__snapshots__/**",
@@ -37,6 +41,11 @@
       "types": "./dist/astryx/*.d.ts",
       "default": "./dist/astryx/*.js"
     },
+    "./doc": {
+      "antscorp-source": "./src/doc/schema.ts",
+      "types": "./dist/doc/schema.d.ts",
+      "default": "./dist/doc/schema.js"
+    },
     "./stylex": {
       "antscorp-source": "./src/stylex.ts",
       "types": "./dist/stylex.d.ts",
@@ -89,19 +98,21 @@
     "astryx:reexports": "bun scripts/astryx-reexports.ts",
     "test": "bun scripts/astryx-reexports.ts --check && vitest run && AUI_REACT_COMPILER=off vitest run --coverage",
     "typecheck": "tsc -p .",
-    "build": "vite build --config vite.build.ts && tsc -p tsconfig.build.json && bun scripts/build-declarations.ts"
+    "build": "vite build --config vite.build.ts && tsc -p tsconfig.build.json && bun scripts/build-declarations.ts && node ../../tools/component-catalog/src/main.ts . && bun build src/cli/main.ts --target=node --outfile=dist/cli.js"
   },
   "dependencies": {
-    "@antscorp/astryx-theme-antsomi": "0.1.2",
+    "@antscorp/astryx-theme-antsomi": "0.1.3",
     "@antscorp/immutable": "0.1.0",
     "@astryxdesign/core": "0.7.4",
     "@codemirror/state": "6.7.6",
     "@codemirror/view": "6.43.14",
     "@stylexjs/stylex": "0.19.1",
-    "spin-delay": "2.0.1"
+    "spin-delay": "2.0.1",
+    "zod": "4.6.5"
   },
   "devDependencies": {
-    "@antscorp/vite-stylex": "0.1.2",
+    "@antscorp/component-catalog": "0.1.0",
+    "@antscorp/vite-stylex": "0.1.3",
     "@storybook/react-vite": "10.6.1",
     "@testing-library/dom": "10.4.2",
     "@testing-library/react": "16.3.3",

package/src/atoms/AddButton.doc.ts

@@ -0,0 +1,36 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for AddButton. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["add", "button", "list", "plus"],
+  usage: {
+    description:
+      "Add a row or item with a labeled plus button. Use TextAction for an action that does not need the add glyph.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep label specific about what will be added and let the host update the list in onClick.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect the button to add data itself; isReadOnly hides the entire editing affordance.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Plus",
+        required: true,
+        description: "The theme's ui:add glyph, sized with the button.",
+      },
+      {
+        name: "Label",
+        required: true,
+        description: "The translated action text, optionally shown in capitals.",
+      },
+    ],
+  },
+  accessibility: ["The button is named by label; uppercase presentation preserves that name."],
+} satisfies ComponentDoc;

package/src/atoms/AddButton.tsx

@@ -15,7 +15,7 @@ export type AddButtonProps = {
   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;

package/src/atoms/AddGlyph.doc.ts

@@ -0,0 +1,26 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for AddGlyph. */
+export const doc = {
+  category: "Data display",
+  keywords: ["plus", "glyph", "icon", "add"],
+  usage: {
+    description:
+      "Draw the theme's decorative plus inside a custom add control. Use AddButton when a complete labeled action is needed.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Match size to the containing button and provide its action label on that button.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not use the glyph alone as an action or expect it to draw in a theme without ui:add.",
+      },
+    ],
+  },
+  accessibility: [
+    "The glyph is decorative and hidden from assistive technology; the containing button supplies the name.",
+  ],
+} satisfies ComponentDoc;

package/src/atoms/Chip.doc.ts

@@ -0,0 +1,45 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for Chip. */
+export const doc = {
+  category: "Data display",
+  keywords: ["pill", "picked value", "remove"],
+  related: [
+    {
+      name: "astryx/Badge",
+      when: "Show an informational status or category rather than a removable picked value.",
+    },
+  ],
+  usage: {
+    description:
+      "Show one picked value in a compact pill. Supply onRemove and labels.remove together to offer removal; the host owns the picked values.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Use a short, recognizable label and provide a translated remove label naming the value.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not use colour alone to explain why a value is invalid; provide surrounding validation text.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Label",
+        required: true,
+        description: "The picked value, truncated with a tooltip when needed.",
+      },
+      {
+        name: "Remove button",
+        required: false,
+        description: "Removes the value; hidden in read-only mode.",
+      },
+    ],
+  },
+  accessibility: [
+    "Name the remove action through labels.remove.",
+    "Hover removal also appears on keyboard focus; keep the action reachable with Tab.",
+  ],
+} satisfies ComponentDoc;

package/src/atoms/Chip.tsx

@@ -103,7 +103,7 @@ export function Chip(props: ChipProps): ReactNode {
 const marker = stylex.defaultMarker();
 
 const styles = stylex.create({
-  // fe-app's chip (ItemPreviewSource): a pill as high as the controls, 10px either side (no
+  // A pill as high as the controls, 10px either side (no
   // spacing step is 10px), in 12px body text of the normal weight. An xstyle, not a `token` theme entry: Token is also
   // drawn by ChipListAddPopover's unframed list in Astryx's own look, which a theme entry would change.
   chip: {
@@ -120,7 +120,7 @@ const styles = stylex.create({
     backgroundColor: "var(--ants-mh-blue-200)",
     color: colorVars["--color-text-primary"],
   },
-  // fe-app's: a 16px white circle over the chip's end (Token's own remove button is 16px too).
+  // A 16px white circle over the chip's end (Token's own remove button is 16px too).
   hoverRemove: {
     position: "absolute",
     insetInlineEnd: spacingVars["--spacing-1"],

package/src/atoms/ChipSkeletons.doc.ts

@@ -0,0 +1,31 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for ChipSkeletons. */
+export const doc = {
+  category: "Feedback",
+  keywords: ["loading", "skeleton", "chips", "placeholder"],
+  usage: {
+    description:
+      "Reserve the shape of picked values while their labels load. Use RowSkeletons for a vertical options list.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Match count, size and shape to the values being loaded, and supply label for the loading status.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not replace already known labels with skeletons unless the whole list is being reloaded.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Chip bars",
+        required: true,
+        description: "A row of rounded shimmer bars with varied widths.",
+      },
+    ],
+  },
+  accessibility: ["The wrapper has role status and uses label as its accessible name."],
+} satisfies ComponentDoc;

package/src/atoms/FieldHeading.doc.ts

@@ -0,0 +1,22 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for FieldHeading. */
+export const doc = {
+  category: "Data display",
+  keywords: ["heading", "caption", "field"],
+  usage: {
+    description:
+      "Show a separate supporting caption above controls whose own labels are hidden. Use FieldRow when the form needs a caption column beside its controls.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep each control's own accessible label even when FieldHeading supplies the visible caption.",
+      },
+      {
+        guidance: false,
+        description: "Do not treat this text as a label association or a semantic heading element.",
+      },
+    ],
+  },
+} satisfies ComponentDoc;