@antscorp/ui 0.1.2 → 0.1.3

package/src/molecules/SplitButton.doc.ts

@@ -0,0 +1,41 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for SplitButton. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["button", "menu", "actions", "split"],
+  usage: {
+    description:
+      "Pair a primary action with a menu of related alternatives. With no items, only the main button is shown.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Use isMainDisabled to block only the primary action, and labels.menu to name the menu arrow.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not assume isLoading disables the alternatives menu; it affects the main action while the menu stays usable.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Main button",
+        required: true,
+        description: "The default action, optionally busy or disabled.",
+      },
+      {
+        name: "Menu button",
+        required: false,
+        description: "A named arrow or host glyph opening the alternatives.",
+      },
+      {
+        name: "Menu",
+        required: false,
+        description: "Related actions, each with its own optional disabled state.",
+      },
+    ],
+  },
+  accessibility: ["label names the main action and labels.menu names the icon-only menu button."],
+} satisfies ComponentDoc;

package/src/molecules/SplitButton.tsx

@@ -37,7 +37,7 @@ export type SplitButtonProps = {
   readonly isMainDisabled?: boolean | undefined;
   /** The main button shows a spinner and is announced as busy; the menu is not affected. */
   readonly isLoading?: boolean | undefined;
-  /** Rounds its two ends into a pill, as fe-app's variant pills; the inner corners stay square. */
+  /** Rounds its two ends into a pill; the inner corners stay square. */
   readonly isRound?: boolean | undefined;
   /** The button's weight, `primary` by default. */
   readonly variant?: "primary" | "secondary" | undefined;

package/src/molecules/StatusButton.doc.ts

@@ -0,0 +1,39 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for StatusButton. */
+export const doc = {
+  category: "Feedback",
+  keywords: ["status", "dot", "button", "connection"],
+  usage: {
+    description:
+      "Combine an action with a small dot showing a related state. Use a plain button when no state needs to be communicated.",
+    bestPractices: [
+      {
+        guidance: true,
+        description: "Translate labels.status to explain the dot independently of its tone.",
+      },
+      {
+        guidance: false,
+        description: "Do not rely on the dot's color alone to convey the state.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Button text",
+        required: true,
+        description: "The action supplied by label.",
+      },
+      {
+        name: "Status dot",
+        required: true,
+        description: "A named dot in the supplied status tone.",
+      },
+      {
+        name: "Icon",
+        required: false,
+        description: "Host-supplied leading content.",
+      },
+    ],
+  },
+  accessibility: ["labels.status names the status dot and label names the action."],
+} satisfies ComponentDoc;

package/src/molecules/TagSelect.doc.ts

@@ -0,0 +1,41 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for TagSelect. */
+export const doc = {
+  category: "Selection",
+  keywords: ["tag", "color", "choice", "popover"],
+  usage: {
+    description:
+      "Choose one value through a small colored tag and a popover of tags. Use Select for a conventional field with a larger options list.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep option labels concise and provide label for the tag button and title for its popover.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not use the colored tag alone to explain the selected value; its text must identify it.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Picked tag",
+        required: true,
+        description: "The selected label, or the raw unknown value in blue.",
+      },
+      {
+        name: "Popover heading",
+        required: false,
+        description: "The supplied title while the tag list is open.",
+      },
+      {
+        name: "Tag choices",
+        required: false,
+        description: "Wrapping tag buttons that choose a value and close the popover.",
+      },
+    ],
+  },
+  accessibility: ["label names the tag button; read-only mode shows the tag without a button."],
+} satisfies ComponentDoc;

package/src/molecules/TagSelect.tsx

@@ -41,8 +41,8 @@ export type TagSelectProps<V extends string> = {
 
 /**
  * A small coloured tag showing the picked value; pressing it opens a popover with a heading and
- * every tag, wrapping, each picked by a press, which closes the popover. As antsomi-ui's
- * `SelectAssociatedTag` tag. Its state is whether the popover is open.
+ * every tag, wrapping, each picked by a press, which closes the popover.
+ * Its state is whether the popover is open.
  */
 export function TagSelect<V extends string>(props: TagSelectProps<V>): ReactNode {
   const { options, value } = props;
@@ -150,7 +150,7 @@ function Tag<V extends string>(props: TagProps<V>): ReactNode {
 }
 
 const styles = stylex.create({
-  // antsomi-ui's SelectedTag (SelectAssociatedTag/styled.ts): 16px high, 3px corners and sides,
+  // The selected tag: 16px high, 3px corners and sides,
   // cut at 70px; no spacing or radius step is 3px.
   tag: {
     display: "inline-flex",
@@ -171,11 +171,11 @@ const styles = stylex.create({
     cursor: { default: "pointer", ":disabled": "default" },
   },
   text: { minWidth: 0 },
-  // antsomi-ui's Popover inner padding (overlayInnerStyle 10), between the 8px and 12px steps.
+  // The popover's 10px inner padding, between the 8px and 12px steps.
   panel: { padding: 10 },
 });
 
-// antsomi-ui's tag fills (SelectAssociatedTag constants), from the antsomi palette.
+// Tag fills from the Antsomi palette.
 const tones = stylex.create({
   cyan: { backgroundColor: "var(--ants-mh-cyan-500)" },
   blue: { backgroundColor: "var(--ants-mh-blue-500)" },

package/src/molecules/ToggleGrid.doc.ts

@@ -0,0 +1,43 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for ToggleGrid. */
+export const doc = {
+  category: "Selection",
+  keywords: ["toggle", "grid", "multiple", "days"],
+  usage: {
+    description:
+      "Choose several compact values in a grid of toggle buttons, such as numbered days or hours. Use CheckGroup for longer checkbox labels.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep value controlled and accept changes in options order; use span for an option that should fill more tracks.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not use the grid for a single exclusive choice or assume toggling preserves click order.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Group label",
+        required: true,
+        description: "Names the set through FieldGroup.",
+      },
+      {
+        name: "Toggle buttons",
+        required: true,
+        description: "One pressed or unpressed button per option, with optional column spans.",
+      },
+      {
+        name: "Error",
+        required: false,
+        description: "A translated selection problem.",
+      },
+    ],
+  },
+  accessibility: [
+    "label names the group; option labels name the toggle buttons and their pressed states show the pick.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/TokenTextField.doc.ts

@@ -0,0 +1,41 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for TokenTextField. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["text", "tokens", "editor", "draft"],
+  related: [{ name: "CommitTextField", when: "Edit ordinary text without atomic token pills." }],
+  usage: {
+    description:
+      "Edit a controlled string containing atomic token pills. pattern returns a fresh global regular expression matching whole tokens and describe supplies their appearance. Local edits commit on blur or single-line Enter; an outside value replaces the draft.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep raw tokens in the string and use onDraftChange only for draft feedback such as a live length counter.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not return a pattern that matches empty strings or treat the visible token label as the stored value.",
+      },
+    ],
+    anatomy: [
+      { name: "Field label", required: true, description: "Names the editable string." },
+      {
+        name: "Editor",
+        required: true,
+        description: "Text and atomic tokens; loads separately with a skeleton.",
+      },
+      {
+        name: "Add button",
+        required: false,
+        description: "Opens the host's picker through onAddClick.",
+      },
+    ],
+  },
+  accessibility: [
+    "Provide label and translated labels.add, labels.remove and labels.loading.",
+    "Use isReadOnly to hide editing affordances while keeping the value readable.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/TransferLayout.doc.ts

@@ -0,0 +1,42 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for TransferLayout. */
+export const doc = {
+  category: "Layout",
+  keywords: ["transfer", "columns", "scroll", "slots"],
+  usage: {
+    description:
+      "Lay out available and picked content in two independently scrolling columns with fixed headers. Use TransferPicker when the kit should also manage selection controls and search.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Name both columns through labels and use startRef when the host observes paging in the start viewport.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect layout slots to implement filtering, picking or removal; those behaviors belong to the host.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Start column",
+        required: true,
+        description: "The start viewport with optional header, fixed title and footer.",
+      },
+      {
+        name: "End column",
+        required: true,
+        description: "The end viewport with an optional fixed title and header.",
+      },
+      {
+        name: "Header strip",
+        required: false,
+        description:
+          "Host controls above the viewports; endHeader is omitted with isEndFullHeight.",
+      },
+    ],
+  },
+  accessibility: ["labels.start and labels.end name the two content columns."],
+} satisfies ComponentDoc;

package/src/molecules/TransferLayout.tsx

@@ -40,7 +40,7 @@ export type TransferLayoutProps = {
 };
 
 /**
- * Two columns side by side in one frame, as fe-app's audience picker: a header strip over two
+ * Two columns side by side in one frame: a header strip over two
  * equal columns of a fixed height whose lists scroll on their own, 1px lines between the parts
  * and no gap, and an optional footer under the start column. The headers and the lists' titles
  * sit outside the scrolling areas. Pure layout: every part is a slot. It holds no state.
@@ -126,8 +126,7 @@ export function TransferLayout({
 
 const LINE_COLOR = "var(--ants-mh-gray-200)";
 
-// fe-app's UITargetSelection grid (WrapperHeaderSelect, WrapperSelectItem, WrapperButtonFooter):
-// lines of its platinum grey, a 41px header strip, columns of a fixed height.
+// Platinum grey grid lines, a 41px header strip, columns of a fixed height.
 const styles = stylex.create({
   frame: {
     gridTemplateColumns: "minmax(0, 1fr) minmax(0, 1fr)",

package/src/molecules/TreeOptions.doc.ts

@@ -0,0 +1,38 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for TreeOptions. */
+export const doc = {
+  category: "Selection",
+  keywords: ["tree", "options", "leaves", "groups"],
+  usage: {
+    description:
+      "Pick one leaf from a flat or two-level tree while groups only expand and collapse. Use TreeSelect to put this tree behind a searchable field trigger.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Give every item a unique value and use isExpandedByDefault at mount when all groups should start open.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not supply deeper nesting and expect it to render; only the top level and its children are shown.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Rows",
+        required: true,
+        description: "Labels with a leaf selection mark or a group's trailing chevron.",
+      },
+      {
+        name: "Child rows",
+        required: false,
+        description: "Leaves indented beneath an expanded group.",
+      },
+    ],
+  },
+  accessibility: [
+    "The named tree exposes treeitem levels, expansion, selection and disabled states; Up and Down move focus, and Enter or Space acts on a row.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/TreeOptions.tsx

@@ -53,7 +53,7 @@ type Row = {
 };
 
 /**
- * The rows of a two-level tree to pick from, as fe-app's tree list: a group row shows its chevron
+ * The rows of a two-level tree to pick from: a group row shows its chevron
  * at the end (right when closed, down when open) and only opens and closes; a leaf is picked; a
  * disabled row does neither. Rows are the Selector's option rows (its styles, its option-row and
  * check theme targets, its check on the picked leaf at the end, where a group shows its chevron),
@@ -100,7 +100,7 @@ export function TreeOptions(props: TreeOptionsProps): ReactNode {
   };
   return (
     // Raw elements: a flat tree (rows with `aria-level`), which Astryx's TreeList is not: it puts
-    // a group's chevron first, fe-app at the end.
+    // a group's chevron first; this tree puts it at the end.
     <div role="tree" aria-label={props.label} onKeyDown={moveFocus}>
       {rows.map((row) => (
         <div
@@ -122,8 +122,8 @@ export function TreeOptions(props: TreeOptionsProps): ReactNode {
           {...rowProps(row, size, value)}
         >
           {/* The option's content and mark column, as `Selector.tsx:1407-1431`. */}
-          {/* One line cut with an ellipsis, the whole label in Text's tooltip when cut, as
-              fe-app's tree (`Tree/Item.jsx:235`); Astryx's SelectorOption would run under the mark. */}
+          {/* One line cut with an ellipsis, with Text's tooltip for the whole label;
+              Astryx's SelectorOption would run under the mark. */}
           <span {...stylex.props(styles.content)}>
             <Text type="inherit" color="inherit" maxLines={1}>
               {row.item.label}
@@ -193,7 +193,7 @@ function moveFocus(event: KeyboardEvent<HTMLDivElement>): void {
 // focus, as the rows take focus, never on the picked row), `itemDisabled` (401-404) and
 // `itemSizeStyles` (452-460). The radius and the picked row's background and weight
 // (`itemSelected`) are left to the theme's `selector-option-row`. Only `child` is ours: a
-// group's leaves one indent step in, as fe-app's.
+// group's leaves one indent step in.
 const styles = stylex.create({
   row: {
     boxSizing: "border-box",
@@ -250,7 +250,7 @@ export function leafOf(items: readonly TreeItem[], value: string): TreeItem | un
   return undefined;
 }
 
-// The rows a search leaves, as fe-app's `searchTree`: a case-insensitive substring of the label.
+// The rows a search leaves: a case-insensitive substring of the label.
 // A leaf stays when it matches; a group when its label or a child's matches, keeping only the
 // children that match.
 export function matchTree(items: readonly TreeItem[], search: string): TreeItem[] {

package/src/organisms/ChipListAddPopover.doc.ts

@@ -0,0 +1,54 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for ChipListAddPopover. */
+export const doc = {
+  category: "Selection",
+  keywords: ["chips", "multiple", "popover", "apply"],
+  related: [
+    {
+      name: "TransferPicker",
+      when: "Keep available rows and picked values visible together with immediate changes.",
+    },
+  ],
+  usage: {
+    description:
+      "Pick several values as removable chips through a searchable checkbox popover. Checkbox edits remain a draft until Apply; closing another way drops them.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Use onRemove to confirm direct chip removal, and separately handle removals arriving in onChange from Apply.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not discard unknown stored values just because options has not loaded them; they remain visible as invalid values or loading placeholders.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Picked values",
+        required: false,
+        description: "Tokens or pill Chips when values are picked, with unknown values retained.",
+      },
+      {
+        name: "Add button",
+        required: false,
+        description: "Opens the checkbox popover unless read-only.",
+      },
+      {
+        name: "Popover",
+        required: false,
+        description: "Search, draft checkboxes and Apply.",
+      },
+      {
+        name: "Error",
+        required: false,
+        description: "A translated selection problem.",
+      },
+    ],
+  },
+  accessibility: [
+    "Supply translated search, add and apply labels plus labels.remove for each chip; labels.loading names loading placeholders.",
+  ],
+} satisfies ComponentDoc;

package/src/organisms/HourOfDayRow.doc.ts

@@ -0,0 +1,43 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for HourOfDayRow. */
+export const doc = {
+  category: "Selection",
+  keywords: ["hours", "day", "schedule", "drag"],
+  usage: {
+    description:
+      "Pick hours in one day by toggling cells or dragging a run. Use HourOfWeekGrid when selections vary by weekday.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Pass hours from 0 to 23 and format names through labels.hour; store the sorted unique result from onChange.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not compress the cells to fit a narrow panel; the row keeps its cell size and scrolls horizontally.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Hour cells",
+        required: true,
+        description: "Twenty-four cells showing picked hours and drag preview.",
+      },
+      {
+        name: "Hour labels",
+        required: true,
+        description: "Every third hour named below the row.",
+      },
+      {
+        name: "Error",
+        required: false,
+        description: "A translated problem below the selection.",
+      },
+    ],
+  },
+  accessibility: [
+    "label names the row; arrow keys move between hours and Space or Enter toggles the focused hour.",
+  ],
+} satisfies ComponentDoc;

package/src/organisms/HourOfDayRow.tsx

@@ -133,7 +133,7 @@ const styles = stylex.create({
   },
   on: { backgroundColor: colorVars["--color-accent"] },
   off: { backgroundColor: colorVars["--color-neutral"] },
-  // fe-app's cells (SelectHoursOfDay Box) turn its hover blue under the pointer, picked or not,
+  // Cells turn hover blue under the pointer, picked or not,
   // while they can be changed.
   liveOn: {
     backgroundColor: {

package/src/organisms/HourOfWeekGrid.doc.ts

@@ -0,0 +1,48 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for HourOfWeekGrid. */
+export const doc = {
+  category: "Selection",
+  keywords: ["hours", "week", "schedule", "grid"],
+  usage: {
+    description:
+      "Pick hours across seven days by dragging a rectangle, toggling a day, or using the everyday row. Use HourOfDayRow when one daily selection is sufficient.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Supply seven day labels Monday first and store cells as day * 24 + hour, from 0 to 167.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not assume read-only matches disabled presentation; read-only hides the everyday editing row while disabled keeps it.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Day rows",
+        required: true,
+        description: "Seven rows of twenty-four hour cells, with day-name actions.",
+      },
+      {
+        name: "Everyday row",
+        required: false,
+        description: "Controls that toggle whole hours across all days, hidden when read-only.",
+      },
+      {
+        name: "Hour axis",
+        required: true,
+        description: "Formatted hour names along the grid.",
+      },
+      {
+        name: "Error",
+        required: false,
+        description: "A translated problem below the grid.",
+      },
+    ],
+  },
+  accessibility: [
+    "label names the grid even when visually hidden; cells expose selection, arrow keys move focus, and Space or Enter toggles a cell.",
+  ],
+} satisfies ComponentDoc;

package/src/organisms/HourOfWeekGrid.tsx

@@ -283,7 +283,7 @@ const styles = stylex.create({
   },
   on: { backgroundColor: colorVars["--color-accent"] },
   off: { backgroundColor: colorVars["--color-neutral"] },
-  // fe-app's cells (SelectHoursOfDay Box) turn its hover blue under the pointer, picked or not,
+  // Cells turn hover blue under the pointer, picked or not,
   // while they can be changed.
   liveOn: {
     backgroundColor: {

package/src/organisms/RepeatableList.doc.ts

@@ -0,0 +1,49 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for RepeatableList. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["list", "repeatable", "add", "rows"],
+  usage: {
+    description:
+      "Compose an editable list whose items and removal controls are supplied by the host. Use RuleList when every item should have a RuleRow and first/rest joining words.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Provide stable itemKey values and pass disabled or read-only state into the controls rendered by renderItem.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not hide the add button yourself at max; the list keeps it disabled with labels.maxReached when supplied.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Items",
+        required: false,
+        description:
+          "Host-rendered rows when items exist, optionally sharing column headings and tracks.",
+      },
+      {
+        name: "Separators",
+        required: false,
+        description: "Joint words or labeled dividers between items.",
+      },
+      {
+        name: "Add row",
+        required: false,
+        description: "A named add button, optionally placed by renderAdd.",
+      },
+      {
+        name: "Feedback",
+        required: false,
+        description: "Empty, maximum and validation messages.",
+      },
+    ],
+  },
+  accessibility: [
+    "label names the list's group; supply labels.add for its add action and accessible names inside rendered items.",
+  ],
+} satisfies ComponentDoc;

package/src/organisms/ResizableDrawer.doc.ts

@@ -0,0 +1,48 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for ResizableDrawer. */
+export const doc = {
+  category: "Overlays",
+  keywords: ["drawer", "resize", "panel", "expand"],
+  usage: {
+    description:
+      "Place a resizable panel at the bottom of its parent, with a fixed header and scrolling body. Expansion covers that parent and Escape shrinks an expanded drawer.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep isExpanded controlled through onExpandedChange and provide labels and glyphs for expand and shrink.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect the drawer to cover the browser viewport unless its parent is sized for that purpose.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Resize bar",
+        required: true,
+        description: "The handle for changing the local drawer height.",
+      },
+      {
+        name: "Header",
+        required: true,
+        description: "Host title, optional end content, expand and close buttons.",
+      },
+      {
+        name: "Banners",
+        required: false,
+        description: "Host messages above the body.",
+      },
+      {
+        name: "Body",
+        required: true,
+        description: "Scrolling host content.",
+      },
+    ],
+  },
+  accessibility: [
+    "label names the drawer; labels names the expand, shrink, close and optional resize controls; Escape shrinks when expanded.",
+  ],
+} satisfies ComponentDoc;