@antscorp/ui 0.1.1 → 0.1.3

package/src/organisms/RuleGroups.doc.ts

@@ -0,0 +1,49 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for RuleGroups. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["rules", "groups", "conditions", "and", "or"],
+  usage: {
+    description:
+      "Edit alternative groups of rules, where all rules in one group must hold. Use RuleList for a single flat conjunction of rules.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep groups controlled and configure controls returned by renderRule for the same disabled or read-only state as the groups.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect a disabled add at maxRules or maxGroups; this view hides adds at their limits and protects the final rule from removal.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Rule cards",
+        required: false,
+        description:
+          "Titled accent cards containing host controls and optional close actions when groups contain rules.",
+      },
+      {
+        name: "And joints",
+        required: false,
+        description: "Words and add-rule buttons within each group.",
+      },
+      {
+        name: "Or dividers",
+        required: false,
+        description: "Dashed separators and the add-group action.",
+      },
+      {
+        name: "Error",
+        required: false,
+        description: "A translated problem with all groups.",
+      },
+    ],
+  },
+  accessibility: [
+    "label names the whole group and labels.remove names rule-card close actions; supplied controls keep their own labels.",
+  ],
+} satisfies ComponentDoc;

package/src/organisms/RuleGroups.tsx

@@ -55,11 +55,11 @@ export type RuleGroupsProps<R> = {
 };
 
 /**
- * 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/src/organisms/RuleList.doc.ts

@@ -0,0 +1,43 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for RuleList. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["rules", "list", "conditions", "joint"],
+  usage: {
+    description:
+      "Edit rules that all must hold, with one joining word on the first row and another on later rows. Use RuleGroups when alternatives need separate groups of rule cards.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Provide stable itemKey values and pass the list's size and lock state to controls returned by renderControls.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect isReadOnly to change host-rendered controls; it hides the list's add and remove actions.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Rule rows",
+        required: true,
+        description: "RuleRow controls with first/rest joint labels and removal actions.",
+      },
+      {
+        name: "Add row",
+        required: false,
+        description: "An optional add action, with a joint when hasAddJoint is enabled.",
+      },
+      {
+        name: "Feedback",
+        required: false,
+        description: "Empty, maximum and validation messages.",
+      },
+    ],
+  },
+  accessibility: [
+    "label names the list; labels.remove and labels.add name editing actions, and each supplied control needs its own label.",
+  ],
+} satisfies ComponentDoc;

package/src/organisms/SearchableGroupedList.doc.ts

@@ -0,0 +1,49 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for SearchableGroupedList. */
+export const doc = {
+  category: "Selection",
+  keywords: ["search", "groups", "list", "tiles"],
+  usage: {
+    description:
+      "Browse host-rendered items in titled groups, filtering locally as text is typed. Use TreeSelect when the result must be a single leaf chosen from two-level groups.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Provide stable group keys and globally unique item keys; use itemText for the text to match and placeholder for independently loading groups.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect isDisabled to block host-rendered item actions; it only affects the uncapped list's search control.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Search",
+        required: true,
+        description: "The local query input with clear action.",
+      },
+      {
+        name: "Group headings",
+        required: true,
+        description: "Titles, optionally toggling collapsed groups.",
+      },
+      {
+        name: "Items",
+        required: true,
+        description:
+          "Host rows or three-column tiles, replaced by group placeholders when supplied.",
+      },
+      {
+        name: "No-match message",
+        required: false,
+        description: "Shown when there are no matching items.",
+      },
+    ],
+  },
+  accessibility: [
+    "Supply labels.search and labels.clear, and scroll.label when using a scrolling region; item renderers supply their own accessible controls.",
+  ],
+} satisfies ComponentDoc;

package/src/organisms/SearchableGroupedList.tsx

@@ -66,7 +66,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?: { readonly maxHeight?: number | undefined; readonly label: string } | undefined;
@@ -271,7 +271,7 @@ const styles = stylex.create({
   framed: { minHeight: 0 },
   capped: (maxHeight: number) => ({ maxHeight }),
   scroll: { minHeight: 0 },
-  // A folding group's row, as fe-app's picker: 10px sides, 36px high when folded.
+  // A folding group's row: 10px sides, 36px high when folded.
   fold: { paddingInline: 10, paddingBlock: 6 },
   flush: { marginInline: -10 },
   title: { fontSize: typeScaleVars["--text-label-size"] },

package/src/organisms/TokenPickerDialog.doc.ts

@@ -0,0 +1,54 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for TokenPickerDialog. */
+export const doc = {
+  category: "Overlays",
+  keywords: ["token", "picker", "definition", "dialog"],
+  usage: {
+    description:
+      "Compose a token definition from a group, a leaf, a display name and fallback text. Use TokenTextField to edit the resulting raw token string inline.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep the definition controlled and reset its draft and items when onGroupChange selects a different group.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect confirmation while loading, without a picked item or with a blank display name; read-only mode hides confirmation.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Dialog heading",
+        required: true,
+        description: "The supplied title.",
+      },
+      {
+        name: "Group and item selectors",
+        required: true,
+        description:
+          "A group choice and a searchable flat or two-level leaf choice, with a loading skeleton when needed.",
+      },
+      {
+        name: "Fallback text",
+        required: true,
+        description: "The controlled defaultValue field.",
+      },
+      {
+        name: "Display name",
+        required: true,
+        description: "A required name, defaulted from the picked leaf until customized.",
+      },
+      {
+        name: "Actions",
+        required: true,
+        description: "Cancel and, when editable, Insert or Save according to mode.",
+      },
+    ],
+  },
+  accessibility: [
+    "Provide the translated group, item, displayName and defaultValue field labels; the dialog uses Astryx Dialog behavior.",
+  ],
+} satisfies ComponentDoc;

package/src/organisms/TransferPicker.doc.ts

@@ -0,0 +1,69 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for TransferPicker. */
+export const doc = {
+  category: "Selection",
+  keywords: ["transfer", "multiple", "picked", "paging"],
+  related: [
+    {
+      name: "ChipListAddPopover",
+      when: "Use compact removable chips and apply checkbox changes as one draft.",
+    },
+  ],
+  usage: {
+    description:
+      "Pick several options in two columns, keeping available rows and removable picks visible together. Use ChipListAddPopover when a compact chip list with an Apply draft is more appropriate.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Supply labels.loadMoreError, labels.retry and onRetryLoadMore together for paging recovery. The error pauses automatic loading; clear it and set isLoadingMore while retrying, then update options and hasMore after success.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not treat select-all as only adding visible rows: when picks already exist, it clears the entire selection, including unknown picks.",
+      },
+      {
+        guidance: true,
+        description:
+          "Supply pickedOptions or pickedLabels for values absent from the loaded options and use onSearchChange when the host performs search.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not replace the current pick with only the visible options after search or paging; unknown picks are intentionally retained.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Available column",
+        required: true,
+        description: "Search, a title and checkbox rows, with optional details and select-all.",
+      },
+      {
+        name: "Picked column",
+        required: true,
+        description: "Framed picked rows with optional remove-all and row actions.",
+      },
+      {
+        name: "Loading and paging rows",
+        required: false,
+        description: "Skeletons or a failed-page retry row that preserve loaded content.",
+      },
+      {
+        name: "Host slots",
+        required: false,
+        description: "Toolbar, end header and footer content.",
+      },
+      {
+        name: "Error",
+        required: false,
+        description: "A translated selection problem below the picker.",
+      },
+    ],
+  },
+  accessibility: [
+    "Supply search, clearSearch, picked and remove labels; disabled and read-only states block picking while search remains usable.",
+  ],
+} satisfies ComponentDoc;

package/src/organisms/TransferPicker.tsx

@@ -142,7 +142,7 @@ export type TransferPickerProps<V extends string> = Pick<
 const LOADING_ROWS = 6;
 
 /**
- * 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
@@ -177,7 +177,7 @@ export function TransferPicker<V extends string>(props: TransferPickerProps<V>):
     <HStack gap={2} align="center" justify={props.endHeader === undefined ? "end" : "between"}>
       {props.endHeader}
       {removeAll !== undefined && (
-        // fe-app keeps it pressable while nothing is picked.
+        // Keep the clear action pressable while nothing is picked.
         <TextAction
           label={removeAll}
           isDisabled={isDisabled}
@@ -365,7 +365,7 @@ function OptionsHeading<V extends string>(
             isLabelHidden
             isDisabled={props.isDisabled ?? false}
             isReadOnly={props.isReadOnly ?? false}
-            // fe-app's box: one mark for "some or all picked", and a click clears them.
+            // One mark for "some or all picked", and a click clears them.
             value={props.value.length > 0 ? "indeterminate" : false}
             onChange={props.onSelectAll}
           />

package/src/organisms/TreeSearchPanel.doc.ts

@@ -0,0 +1,43 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for TreeSearchPanel. */
+export const doc = {
+  category: "Selection",
+  keywords: ["tree", "search", "panel", "paging"],
+  usage: {
+    description:
+      "Compose the search and results panel used inside TreeSelect. Use TreeSelect for a complete trigger and popover around this panel.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep search value and selectedValue controlled, and use isSearchedByHost when items are already filtered remotely.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect the panel to close a surrounding popover after onPick; its host owns that behavior.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Search input",
+        required: true,
+        description: "A controlled query that focuses a frame after mounting.",
+      },
+      {
+        name: "Results",
+        required: true,
+        description: "TreeOptions, loading rows or a no-match message.",
+      },
+      {
+        name: "Paging row",
+        required: false,
+        description: "A load-more sentinel, loading placeholders or a retry action.",
+      },
+    ],
+  },
+  accessibility: [
+    "label names the tree and labels supplies the search and clear names; TreeOptions handles row focus and keyboard activation.",
+  ],
+} satisfies ComponentDoc;

package/src/organisms/TreeSearchPanel.tsx

@@ -14,7 +14,7 @@ import { LoadMoreRow } from "../molecules/LoadMoreRow";
 import { matchTree, TreeOptions } from "../molecules/TreeOptions";
 import type { TreeSelectItem, TreeSelectProps } from "./TreeSelect";
 
-// fe-app's tree list is at most 200px high (UISelectCondition `Tree/index.jsx`).
+// Cap the tree list at 200px so longer results scroll inside the panel.
 const LIST_HEIGHT = 200;
 
 /** What `TreeSearchPanel` takes. */

package/src/organisms/TreeSelect.doc.ts

@@ -0,0 +1,56 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for TreeSelect. */
+export const doc = {
+  category: "Selection",
+  keywords: ["tree", "select", "search", "leaf"],
+  related: [
+    { name: "Select", when: "Choose one value from flat options or sections without a tree." },
+  ],
+  usage: {
+    description:
+      "Choose a single leaf through a searchable two-level tree in a popover. Use Select for a conventional flat or sectioned options list.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Supply labels.search, labels.noMatch and labels.clear for the panel. For paging recovery, supply labels.loadMoreError, labels.retry and onRetryLoadMore together; clear the error and set isLoadingMore while retrying, then update items and hasMore after success.",
+      },
+      {
+        guidance: true,
+        description:
+          "Keep item values unique and supply labels.value for a selected leaf that is absent from the loaded items.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect group rows to become selected values or nesting deeper than two levels to render.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Trigger",
+        required: true,
+        description: "The selected label or placeholder, with loading or read-only presentation.",
+      },
+      {
+        name: "Start addon",
+        required: false,
+        description: "A separate host control sharing the frame, outside the trigger button.",
+      },
+      {
+        name: "Panel",
+        required: false,
+        description: "Search, a tree, and optional paging or retry rows while the popover is open.",
+      },
+      {
+        name: "Error",
+        required: false,
+        description: "A translated problem below the trigger.",
+      },
+    ],
+  },
+  accessibility: [
+    "Supply label even when hidden; the tree supports Up and Down, Enter and Space, and Escape closes the popover.",
+  ],
+} satisfies ComponentDoc;

package/src/organisms/TreeSelect.tsx

@@ -88,7 +88,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;
@@ -105,8 +105,8 @@ export type TreeSelectProps = Pick<LoadMoreOptions, "onLoadMore" | "hasMore" | "
 };
 
 /**
- * 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
@@ -289,7 +289,7 @@ const styles = stylex.create({
     cursor: { default: "pointer", ":disabled": "default" },
   },
   // With an addon the frame has the input look and lays out the addon, the line and the trigger;
-  // fe-app's SelectAssociatedTag: 5px before the tag, the line 6px after it and 1px before the
+  // The tag's inset: 5px before the tag, the line 6px after it and 1px before the
   // select (no spacing step is 5px, 6px or 1px).
   frame: {
     display: "flex",

package/src/theme/AntsomiTheme.doc.ts

@@ -0,0 +1,23 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for AntsomiTheme. */
+export const doc = {
+  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: true,
+        description:
+          "Import @antscorp/ui/theme.css separately and load Roboto in the host; nest providers when an override should affect only a subtree.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect the provider to load CSS or fonts, or replace theme tokens with hard-coded colors in consuming views.",
+      },
+    ],
+  },
+} satisfies ComponentDoc;