@antscorp/ui 0.1.2 → 0.1.3

package/src/molecules/InlineEditableText.doc.ts

@@ -0,0 +1,41 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for InlineEditableText. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["inline", "text", "edit", "draft"],
+  usage: {
+    description:
+      "Edit a title or body text in place, committing on blur or Enter without a separate edit mode. Use CommitTextField for a conventional labeled field.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Supply both labels.edit and icons.edit to offer a pencil that focuses the input.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect a field or pencil in read-only mode; the view renders plain text with the placeholder when empty.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Text",
+        required: true,
+        description: "A draft input, or plain text in read-only mode.",
+      },
+      {
+        name: "Trailing content",
+        required: false,
+        description: "The after slot between the text and pencil.",
+      },
+      {
+        name: "Pencil",
+        required: false,
+        description: "A named host-supplied edit glyph shown on hover.",
+      },
+    ],
+  },
+  accessibility: ["label names the input; labels.edit names the optional pencil button."],
+} satisfies ComponentDoc;

package/src/molecules/LoadMoreRow.doc.ts

@@ -0,0 +1,36 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for LoadMoreRow. */
+export const doc = {
+  category: "Feedback",
+  keywords: ["pagination", "loading", "retry", "sentinel"],
+  usage: {
+    description:
+      "Finish a paged list with loading placeholders or a failed-page retry action. Use LoadState for the initial load that replaces the whole content.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep loaded rows above this view and attach sentinelRef to the host's load-more observer.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not pass error without onRetry and expect an error row; both are needed to show it.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Loading rows",
+        required: false,
+        description: "Two timed skeleton rows in the requested variant.",
+      },
+      {
+        name: "Retry row",
+        required: false,
+        description: "The translated error and retry button.",
+      },
+    ],
+  },
+  accessibility: ["Supply a clear translated labels.retry for the retry button."],
+} satisfies ComponentDoc;

package/src/molecules/LoadState.doc.ts

@@ -0,0 +1,42 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for LoadState. */
+export const doc = {
+  category: "Feedback",
+  keywords: ["loading", "error", "retry", "placeholder"],
+  usage: {
+    description:
+      "Switch between a content-shaped loading placeholder, a failure with retry, and loaded children. Use LoadMoreRow for later pages so existing results can remain visible.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Choose FieldSkeleton or RowSkeletons as placeholder and give that placeholder its loading status name.",
+      },
+      {
+        guidance: false,
+        description: "Do not use a generic spinner in place of the content-shaped skeleton.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Placeholder",
+        required: false,
+        description: "Host-supplied skeleton content while loading.",
+      },
+      {
+        name: "Error",
+        required: false,
+        description: "A failure title, optional detail and retry button.",
+      },
+      {
+        name: "Content",
+        required: false,
+        description: "The children after loading succeeds.",
+      },
+    ],
+  },
+  accessibility: [
+    "The placeholder names its own loading status; labels.retry names the error action.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/MetaTable.doc.ts

@@ -0,0 +1,46 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for MetaTable. */
+export const doc = {
+  category: "Data display",
+  keywords: ["table", "metadata", "names", "counts"],
+  usage: {
+    description:
+      "Display a read-only list of names with an optional short-value column. Use TransferPicker when users need to edit the picked values.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Provide labels.meta to show the meta column and labels.loading when rows are loading.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect a row with error to remain a link; its name becomes plain error-toned text with an explanation.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Name column",
+        required: true,
+        description: "A heading and names, optionally linked in a new tab.",
+      },
+      {
+        name: "Meta column",
+        required: false,
+        description: "Short values under labels.meta.",
+      },
+      {
+        name: "Problem tip",
+        required: false,
+        description: "A warning explanation for an invalid row.",
+      },
+      {
+        name: "Loading cells",
+        required: false,
+        description: "Shimmer bars in the real columns for loading rows.",
+      },
+    ],
+  },
+  accessibility: ["The first loading row provides the one status named by labels.loading."],
+} satisfies ComponentDoc;

package/src/molecules/MetaTable.tsx

@@ -47,7 +47,7 @@ export type MetaTableProps = {
 };
 
 /**
- * A read-only table of names and a short value each, as fe-app shows a pick in view mode: a name
+ * A read-only table of names and a short value each: a name
  * column (each name a link when it has an `href`, on one line with the whole name in a tooltip when
  * cut; a problem in the error tone with a ⚠ tip) and, with `labels.meta`, a value column at the
  * end. A row that `isLoading` shows shimmer bars in its cells, in the table's real columns; the

package/src/molecules/PercentRow.doc.ts

@@ -0,0 +1,48 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for PercentRow. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["percent", "slider", "share", "commit"],
+  usage: {
+    description:
+      "Edit a whole percentage through a number input and a bounded slider. Dragging previews locally and reports the change only when the interaction ends.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Use onChange to store committed values and isRemoveDisabled when removal must also be blocked.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not assume isDisabled blocks removal; it locks the share while the optional remove action stays active.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Caption",
+        required: false,
+        description: "The FieldRow caption beside the controls.",
+      },
+      {
+        name: "Percent input",
+        required: true,
+        description: "The controlled whole percentage.",
+      },
+      {
+        name: "Slider",
+        required: true,
+        description: "A bounded percentage control with local drag preview.",
+      },
+      {
+        name: "Remove button",
+        required: false,
+        description: "A named removal action supplied through onRemove.",
+      },
+    ],
+  },
+  accessibility: [
+    "labels.share names the controls and labels.remove names the optional remove button.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/PhoneFrame.doc.ts

@@ -0,0 +1,46 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for PhoneFrame. */
+export const doc = {
+  category: "Layout",
+  keywords: ["phone", "preview", "device", "content"],
+  usage: {
+    description:
+      "Preview content inside a drawn phone with a status bar and titled header. Use it for a visual preview rather than interactive device navigation.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Give title a recognizable name and keep preview content readable within the scrolling body.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect the drawn back chevron or status-bar symbols to perform actions.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Device frame",
+        required: true,
+        description: "A rounded phone outline with a camera island.",
+      },
+      {
+        name: "Status bar",
+        required: true,
+        description: "Clock, signal and battery imagery.",
+      },
+      {
+        name: "Header",
+        required: true,
+        description: "A back chevron, avatar and title.",
+      },
+      {
+        name: "Content",
+        required: true,
+        description: "Host preview content that scrolls within the device.",
+      },
+    ],
+  },
+  accessibility: ["The frame is a figure named by title."],
+} satisfies ComponentDoc;

package/src/molecules/PhoneFrame.tsx

@@ -21,7 +21,7 @@ export type PhoneFrameProps = {
 };
 
 /**
- * A phone to preview content in, as antsomi-ui's `MobileFrameV3` with its `MobileBrandingBar`,
+ * A phone frame with a branding bar to preview content in,
  * drawn rather than pictured: a dark rounded device with a camera island, a status bar (clock,
  * signal, battery), a header with a back chevron, the avatar and the title, and the content under
  * it, scrolling when it is taller than the screen. As wide as its container, up to 290px, with a
@@ -77,7 +77,7 @@ export function PhoneFrame({ title, avatarSrc, labels, children }: PhoneFramePro
 const BARS = ["s", "m", "l", "xl"] as const;
 
 const styles = stylex.create({
-  // antsomi-ui's medium frame: 290 × 600 at most. The bezel is black with a slate rim; no Astryx
+  // A medium frame: 290 × 600 at most. The bezel is black with a slate rim; no Astryx
   // surface is a device, so the antsomi palette draws it.
   device: {
     boxSizing: "border-box",

package/src/molecules/ProblemsButton.doc.ts

@@ -0,0 +1,41 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for ProblemsButton. */
+export const doc = {
+  category: "Feedback",
+  keywords: ["errors", "problems", "popover", "count"],
+  usage: {
+    description:
+      "Summarize validation problems in a count button that opens a selectable list. The view renders nothing when items is empty.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Translate labels.count with the problem count and use onPick's index to locate the corresponding problem.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not assume picking a problem fixes it; the host decides how to reveal or address it.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Count button",
+        required: true,
+        description: "An error glyph and the number of problems when there are problems.",
+      },
+      {
+        name: "Popover",
+        required: false,
+        description: "A titled, scrollable list built while open.",
+      },
+      {
+        name: "Problem actions",
+        required: false,
+        description: "A button per problem that reports its index and closes the popover.",
+      },
+    ],
+  },
+  accessibility: ["labels.count names the count button; title labels the problem list."],
+} satisfies ComponentDoc;

package/src/molecules/RemovableRow.doc.ts

@@ -0,0 +1,48 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for RemovableRow. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["picked", "row", "remove", "framed"],
+  usage: {
+    description:
+      "Show a picked value with supporting text and a remove action. Use CheckRow when the row is an option to tick instead.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Name the removal through labels.remove and use isFramed when picked values need bordered single-line rows.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect isReadOnly to hide host-supplied hover actions; the host must make those appropriate for viewing.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Text",
+        required: true,
+        description: "The value label with an optional description.",
+      },
+      {
+        name: "Problem",
+        required: false,
+        description: "Validation text below an unframed row or a warning tip in a framed row.",
+      },
+      {
+        name: "End content",
+        required: false,
+        description: "Host content optionally swapped for hover actions.",
+      },
+      {
+        name: "Remove button",
+        required: false,
+        description: "Removes the picked value unless read-only.",
+      },
+    ],
+  },
+  accessibility: [
+    "labels.remove names the remove button; name interactive host-supplied hover actions separately.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/RemovableRow.tsx

@@ -36,7 +36,7 @@ export type RemovableRowProps = {
    */
   readonly hoverContent?: ReactNode;
   /**
-   * A bordered box around the row, as fe-app's picked items: its text on one line, the whole text
+   * A bordered box around the row: its text on one line, the whole text
    * in a tooltip when cut. As high as `RowSkeletons variant="framed"`.
    */
   readonly isFramed?: boolean | undefined;
@@ -134,7 +134,7 @@ export function RemovableRow(props: RemovableRowProps): ReactNode {
 const styles = stylex.create({
   // The texts take the room the end content and the remove button leave, so they wrap.
   text: { minWidth: 0, flexGrow: 1 },
-  // fe-app's picked item (UITargetSelection ColumnSelection WrapperLabelV2): a 1px platinum
+  // A picked item's frame: a 1px platinum
   // border, 5px corners and 8px padding (the `padding` step 2).
   frame: {
     borderWidth: borderVars["--border-width"],

package/src/molecules/RevealRadioGroup.doc.ts

@@ -0,0 +1,41 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for RevealRadioGroup. */
+export const doc = {
+  category: "Selection",
+  keywords: ["radio", "choice", "reveal", "details"],
+  usage: {
+    description:
+      "Choose one option and reveal only its related content below the list or beneath that option. Use RevealSwitch for a single boolean setting.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep value controlled and choose contentPlacement=option when each option's detail should follow its label.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect the group to make controls inside option content read-only or disabled; configure those controls in the host.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Group label",
+        required: true,
+        description: "The group's name, optionally visually hidden.",
+      },
+      {
+        name: "Radio options",
+        required: true,
+        description: "The mutually exclusive choices with optional explanatory tips.",
+      },
+      {
+        name: "Revealed content",
+        required: false,
+        description: "Only the chosen option's content.",
+      },
+    ],
+  },
+  accessibility: ["Supply label even when isLabelHidden, and clear labels for every option."],
+} satisfies ComponentDoc;

package/src/molecules/RevealSwitch.doc.ts

@@ -0,0 +1,38 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for RevealSwitch. */
+export const doc = {
+  category: "Selection",
+  keywords: ["switch", "boolean", "reveal", "settings"],
+  usage: {
+    description:
+      "Turn a setting on or off and reveal its controls only while it is on. Use RevealRadioGroup when choosing among several alternatives.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep value controlled and give the switch a label that explains what enabling it does.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect disabling or making the switch read-only to change the behavior of supplied children.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Switch",
+        required: true,
+        description: "The labeled boolean control.",
+      },
+      {
+        name: "Content",
+        required: false,
+        description: "Host controls shown below the switch while value is true.",
+      },
+    ],
+  },
+  accessibility: [
+    "label names the switch; the host supplies accessible labels for revealed controls.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/RuleRow.doc.ts

@@ -0,0 +1,43 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for RuleRow. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["rule", "row", "joint", "remove"],
+  usage: {
+    description:
+      "Arrange a joining word, host controls and a remove button on a wrapping row. Inside RepeatableList with columns, the row uses the shared grid tracks.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Give host controls the row's size and use align=start when a control shows validation below its input.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not assume isDisabled or isReadOnly changes the supplied controls; those flags control the row's remove affordance.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Joint word",
+        required: false,
+        description: "The translated word joining this row to its predecessor.",
+      },
+      {
+        name: "Controls",
+        required: true,
+        description: "Host-supplied fields, operators and values.",
+      },
+      {
+        name: "Remove button",
+        required: false,
+        description: "A named action, with its grid track preserved in read-only column layouts.",
+      },
+    ],
+  },
+  accessibility: [
+    "labels.remove names the remove button; each supplied control needs its own label.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/Select.doc.ts

@@ -0,0 +1,62 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for Select. */
+export const doc = {
+  category: "Selection",
+  keywords: ["choice", "options", "search"],
+  related: [
+    { name: "TreeSelect", when: "Choose one leaf from a two-level tree." },
+    {
+      name: "ChipListAddPopover",
+      when: "Choose multiple values in a compact popover with an Apply draft.",
+    },
+    {
+      name: "TransferPicker",
+      when: "Choose multiple values with available and picked rows visible together.",
+    },
+  ],
+  example: "Default",
+  usage: {
+    description:
+      "Choose one value from options, optionally grouped into sections. Keep value controlled and update it through onChange. Offer onClear when the selection may be empty.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Use hasSearch for long lists and keep the known label available through labels.value while options load.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not supply labels.warning alongside error expecting both to appear; warning takes precedence over the validation error.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not disable a field merely to display its value; use isReadOnly when editing is unavailable.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Field label",
+        required: true,
+        description: "Names the choice even when visually hidden.",
+      },
+      {
+        name: "Trigger",
+        required: true,
+        description: "Shows the selected value or placeholder and opens the list.",
+      },
+      {
+        name: "Options",
+        required: false,
+        description:
+          "The choices, sections and optional search field, while the list is open and editable.",
+      },
+    ],
+  },
+  accessibility: [
+    "Always provide label, including when isLabelHidden is true.",
+    "Supply translated description and error text so the choice and its validation are clear.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/Select.tsx

@@ -34,7 +34,7 @@ export type SelectProps = {
   readonly hasSearch?: boolean | undefined;
   /** The trigger's look: an underlined field (`input`, the default) or a bare text button (`ghost`). */
   readonly variant?: "input" | "ghost" | 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;
   /** The trigger's width, in pixels or any CSS length such as `"100%"`. */
   readonly width?: number | string | undefined;
@@ -69,7 +69,7 @@ export type SelectProps = {
 };
 
 /**
- * The kit's select, as antd's Select in fe-app, on Astryx's `Selector`: the list is as wide as the
+ * The kit's select on Astryx's `Selector`: the list is as wide as the
  * trigger (the theme) and a long option label ends in an ellipsis with the whole label in a
  * tooltip. Every select is one rather than Astryx's `Selector` (lint-enforced). It holds no state.
  */

package/src/molecules/SideLabelRow.doc.ts

@@ -0,0 +1,35 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for SideLabelRow. */
+export const doc = {
+  category: "Layout",
+  keywords: ["card", "row", "caption", "responsive"],
+  usage: {
+    description:
+      "Place a narrow caption beside controls inside a card, with padding for the card's rows. Use FieldRow for a form section with theme-driven caption and control widths.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep labelWidth consistent across the card and let controls move below the caption when space runs out.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not treat the visual caption as an accessible label association for every supplied control.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Caption",
+        required: true,
+        description: "The narrow label column, wrapping long text.",
+      },
+      {
+        name: "Controls",
+        required: true,
+        description: "Host content beside the caption or beneath it in a narrow layout.",
+      },
+    ],
+  },
+} satisfies ComponentDoc;

package/src/molecules/SideLabelRow.tsx

@@ -17,7 +17,7 @@ export type SideLabelRowProps = {
 
 /**
  * One row of a card: a narrow label column and the row's controls, padded as a card's rows are.
- * The label sits centred on the first line of controls (`md` high, fe-app's 30px); where the controls would get
+ * The label sits centred on the first line of controls (`md` high, the theme's 30px); where the controls would get
  * narrower than 240px they move under the label. It holds no state.
  */
 export function SideLabelRow({ label, labelWidth = 90, children }: SideLabelRowProps): ReactNode {
@@ -34,7 +34,7 @@ export function SideLabelRow({ label, labelWidth = 90, children }: SideLabelRowP
 }
 
 const styles = stylex.create({
-  // fe-app's rows (UIPerformEventV2 DataSourceBlockContent): 10px above and below, between the
+  // Rows have 10px above and below, between the
   // spacing steps of 8px and 12px.
   row: { paddingBlock: 10 },
   // As high as an `md` control, so the text is centred on the first line of controls.