@antscorp/ui 0.1.2 → 0.1.3

package/src/molecules/AccentCard.tsx

@@ -39,9 +39,8 @@ export type AccentCardProps = {
   readonly isDisabled?: boolean | undefined;
   /**
    * `stripe` (default): a grey border with an accent stripe down the start edge and a light
-   * header bar, as fe-app's Perform event card. `banner`: no border nor stripe but a soft shadow,
-   * under a dark blue header bar with the title in white capitals and a white close cross, as
-   * fe-app's audience picker.
+   * header bar. `banner`: no border nor stripe but a soft shadow,
+   * under a dark blue header bar with the title in white capitals and a white close cross.
    */
   readonly variant?: "stripe" | "banner" | undefined;
 };
@@ -103,7 +102,7 @@ export function AccentCard(props: AccentCardProps): ReactNode {
 }
 
 const styles = stylex.create({
-  // fe-app's Perform event card (UIPerformEventV2 GeneralContainerCondition): a grey border and a
+  // A grey border and a
   // 4px accent stripe at the start (no border token is 4px). A look of this card only, which no
   // Card prop nor theme entry (it would paint every card) can express; `padding={0}` clears the rest.
   card: {
@@ -111,17 +110,17 @@ const styles = stylex.create({
     borderInlineStartWidth: 4,
     borderInlineStartColor: colorVars["--color-accent"],
   },
-  // fe-app's header bar: 10px above and below, between the spacing steps of 8px and 12px, and as
+  // The header bar: 10px above and below, between the spacing steps of 8px and 12px, and as
   // high with the close button (sm) as without it.
   header: {
     paddingBlock: 10,
     minHeight: `calc(${sizeVars["--size-element-sm"]} + ${spacingVars["--spacing-5"]})`,
     backgroundColor: "var(--ants-mh-gray-75)",
   },
-  // fe-app's audience picker (UITargetSelection ContainerTargetAudience): no border, square
-  // corners and a soft shadow (Astryx's low elevation, near fe-app's 0 1px 4px grey).
+  // The banner card: no border, square
+  // corners and a soft shadow (Astryx's low elevation, near a 0 1px 4px grey shadow).
   bannerCard: { borderStyle: "none", borderRadius: 0 },
-  // fe-app's HeaderTargetAudience: white semibold capitals on its header blue, 10px 20px around.
+  // White semibold capitals on the header blue, 10px 20px around.
   banner: {
     backgroundColor: "var(--ants-mh-blue-750)",
     color: colorVars["--color-on-accent"],

package/src/molecules/CheckGroup.doc.ts

@@ -0,0 +1,40 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for CheckGroup. */
+export const doc = {
+  category: "Selection",
+  keywords: ["checkboxes", "multiple", "options", "group"],
+  usage: {
+    description:
+      "Choose several values from a short list of labeled checkboxes. Use ToggleGrid when a compact grid of toggle buttons fits the choices better.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep value controlled and accept onChange values in options order; use vertical orientation when labels need more room.",
+      },
+      {
+        guidance: false,
+        description: "Do not use checkboxes for mutually exclusive choices; use RevealRadioGroup.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Group label",
+        required: true,
+        description: "Names the set through FieldGroup.",
+      },
+      {
+        name: "Checkboxes",
+        required: true,
+        description: "One controlled checkbox per option, in a wrapping row or column.",
+      },
+      {
+        name: "Error",
+        required: false,
+        description: "A translated problem with the selection.",
+      },
+    ],
+  },
+  accessibility: ["Supply label for the group and a clear label on every option."],
+} satisfies ComponentDoc;

package/src/molecules/CheckRow.doc.ts

@@ -0,0 +1,43 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for CheckRow. */
+export const doc = {
+  category: "Selection",
+  keywords: ["checkbox", "row", "pick", "list"],
+  usage: {
+    description:
+      "Show one checkbox choice with optional supporting text and end content. Use RemovableRow for a value that is already picked and needs a removal action.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep label meaningful because it names the checkbox, and reserve hoverContent for supplementary row actions.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not assume clicking the text toggles the checkbox; the checkbox itself is the control.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Checkbox",
+        required: true,
+        description: "The controlled boolean choice.",
+      },
+      {
+        name: "Text",
+        required: true,
+        description: "A one-line label and optional one-line description.",
+      },
+      {
+        name: "End content",
+        required: false,
+        description: "A value optionally replaced by hover actions.",
+      },
+    ],
+  },
+  accessibility: [
+    "label names the checkbox; provide names on interactive controls supplied through hoverContent.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/CheckRow.tsx

@@ -36,7 +36,7 @@ export type CheckRowProps = {
  * One row of a list to tick: a checkbox (md, as every checkbox), the row's text on one line (and
  * an optional second line), and content at its end that `hoverContent` replaces while the row is
  * hovered or focused. The box is the control and is named by the text; the text itself is not a
- * click target, as in fe-app. As high as a small control, so `RowSkeletons variant="check"`
+ * click target. As high as a small control, so `RowSkeletons variant="check"`
  * stands in for it without a shift. It holds no state.
  */
 export function CheckRow(props: CheckRowProps): ReactNode {

package/src/molecules/ChoiceDialog.doc.ts

@@ -0,0 +1,48 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for ChoiceDialog. */
+export const doc = {
+  category: "Overlays",
+  keywords: ["dialog", "choice", "confirm", "radio"],
+  usage: {
+    description:
+      "Ask for one choice before confirming a change, with optional details under the selected option. Use ConfirmDialog when no choice is required.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep value and option details controlled, and use isConfirmDisabled while the selected details are incomplete.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not apply the choice merely when onValueChange fires; onConfirm is the explicit confirmation action.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Header",
+        required: true,
+        description: "The question supplied by title.",
+      },
+      {
+        name: "Description",
+        required: true,
+        description: "Explains what the user is choosing.",
+      },
+      {
+        name: "Choices",
+        required: true,
+        description: "A radio list revealing the selected option's detail.",
+      },
+      {
+        name: "Actions",
+        required: true,
+        description: "Translated cancel and confirm buttons.",
+      },
+    ],
+  },
+  accessibility: [
+    "Provide descriptive title and option labels; closing the dialog, including Escape, calls onCancel.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/ChoiceTiles.doc.ts

@@ -0,0 +1,42 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for ChoiceTiles. */
+export const doc = {
+  category: "Selection",
+  keywords: ["tiles", "choices", "actions", "cards"],
+  usage: {
+    description:
+      "Offer a few actions as cards with an icon, title and short description. Use RevealRadioGroup when a persistent selected value is required.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Make each title distinguish the action and use onSelect to show or perform what follows.",
+      },
+      {
+        guidance: false,
+        description: "Do not use tiles as toggles; this view has no selected state.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Icon circle",
+        required: true,
+        description: "Host glyph displayed in an accent circle on each tile.",
+      },
+      {
+        name: "Title",
+        required: true,
+        description: "The bold action text and button name.",
+      },
+      {
+        name: "Description",
+        required: true,
+        description: "Supporting text limited to two lines.",
+      },
+    ],
+  },
+  accessibility: [
+    "label names the group; each tile is a button named by its title and supports click, Enter and Space.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/ChoiceTiles.tsx

@@ -32,7 +32,7 @@ export type ChoiceTilesProps<V extends string> = {
 };
 
 /**
- * A choice among a few ways to go on, as antsomi-ui's tiles: a wrapping row of 180×170 cards, each
+ * A choice among a few ways to go on: a wrapping row of 180×170 cards, each
  * a button with its glyph in a soft accent circle, a bold title and a description under it. A pick
  * is an action, not a selected state: the host shows what follows instead. It holds no state.
  */
@@ -64,13 +64,13 @@ export function ChoiceTiles<V extends string>(props: ChoiceTilesProps<V>): React
   );
 }
 
-// fe-app's tiles are 150×130 at its 12px text; ours is larger, so a two-line description fits here.
+// A 150×130 tile at 12px text is too tight; 180×170 leaves room for a two-line description.
 const TILE = { width: 180, height: 170 } as const;
 
 const styles = stylex.create({
   // Text has no alignment prop: its lines centre under the glyph from here.
   fill: { height: "100%", textAlign: "center" },
-  // antsomi-ui's tile glyph: a 50px circle in the accent's lightest tint, the glyph in the accent.
+  // A 50px circle in the accent's lightest tint, the glyph in the accent.
   circle: {
     flexShrink: 0,
     width: 50,

package/src/molecules/CommitTextField.doc.ts

@@ -0,0 +1,41 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for CommitTextField. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["text", "draft", "commit", "blur"],
+  related: [{ name: "TokenTextField", when: "Matched tokens need to appear as atomic pills." }],
+  usage: {
+    description:
+      "Edit text locally and report a single change on blur or single-line Enter. Use TokenTextField when matched tokens need to appear as atomic pills.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Return accepted text through value; use isDraftKeptOnCommit only when a refused draft should remain visible.",
+      },
+      {
+        guidance: false,
+        description: "Do not expect Enter to commit a multiline field; it inserts a new line.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Label",
+        required: true,
+        description: "The field's accessible name, optionally visually hidden.",
+      },
+      {
+        name: "Input",
+        required: true,
+        description: "A single-line control or a multiline text area holding a draft.",
+      },
+      {
+        name: "Help and error",
+        required: false,
+        description: "Translated description and validation text.",
+      },
+    ],
+  },
+  accessibility: ["Always supply label, including when isLabelHidden is true."],
+} satisfies ComponentDoc;

package/src/molecules/ConfirmDialog.doc.ts

@@ -0,0 +1,43 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for ConfirmDialog. */
+export const doc = {
+  category: "Overlays",
+  keywords: ["confirmation", "dialog", "cancel", "loss"],
+  usage: {
+    description:
+      "Ask before a change that loses work, optionally paired with useConfirmedChange. Use ChoiceDialog when the user must choose an option before confirming.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Explain the consequence in description and make labels.action name the actual change.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not perform the pending change until onConfirm; onCancel should discard the pending request.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Header",
+        required: true,
+        description: "The confirmation question supplied by title.",
+      },
+      {
+        name: "Description",
+        required: true,
+        description: "The consequence of the pending change.",
+      },
+      {
+        name: "Actions",
+        required: true,
+        description: "The cancel button and confirming action.",
+      },
+    ],
+  },
+  accessibility: [
+    "Supply a clear title and translated action and cancel labels; dialog behavior is provided by Astryx Dialog.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/DateTimeInput.doc.ts

@@ -0,0 +1,48 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for DateTimeInput. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["date", "time", "partial", "calendar"],
+  usage: {
+    description:
+      "Edit a local date and time even while either part is incomplete. Set hasTime=false for a date-only value; labels.timezone only displays a note.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep wire values as strings and use frame=none when the individual date and time labels should be visible.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not require the value to be complete on every onChange; empty and partial strings are supported.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Date input",
+        required: true,
+        description: "The date portion, optionally constrained by min.",
+      },
+      {
+        name: "Time input",
+        required: false,
+        description: "The time portion when hasTime is enabled.",
+      },
+      {
+        name: "Note",
+        required: false,
+        description: "labels.timezone shown beside the time.",
+      },
+      {
+        name: "Help and error",
+        required: false,
+        description: "Group guidance or date-field guidance with frame=none.",
+      },
+    ],
+  },
+  accessibility: [
+    "Supply label and labels.date and labels.time; the default bare group hides the individual visible labels while preserving their names.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/DurationInput.doc.ts

@@ -0,0 +1,36 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for DurationInput. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["duration", "days", "hours", "seconds"],
+  usage: {
+    description:
+      "Edit a length of time as days, hours, minutes and seconds. Use DateTimeInput for a calendar date and time instead of an elapsed duration.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Translate every unit label and use max to constrain parts; reaching max.days disables the remaining parts.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not treat this partial duration object as an instant or assume unset parts are explicitly stored as zero.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Part inputs",
+        required: true,
+        description: "Four number inputs, each followed by its translated unit.",
+      },
+      {
+        name: "Error",
+        required: false,
+        description: "A translated problem with the whole duration.",
+      },
+    ],
+  },
+  accessibility: ["label names the unframed group; labels names each unit's input."],
+} satisfies ComponentDoc;

package/src/molecules/DurationInput.tsx

@@ -44,7 +44,7 @@ export function DurationInput(props: DurationInputProps): ReactNode {
   const size = props.size ?? "md";
   const duration = props.value ?? {};
   const isWholeDays = max.days !== undefined && duration.days === max.days;
-  // As fe-app's: with any other part set, days stop one short, so they never reach a max that disables those parts.
+  // With any other part set, days stop one short, so they never reach a max that disables those parts.
   const hasParts = PARTS.some((part) => part !== "days" && (duration[part] ?? 0) > 0);
   const limits = { ...max, ...(max.days !== undefined && hasParts && { days: max.days - 1 }) };
   return (
@@ -55,7 +55,7 @@ export function DurationInput(props: DurationInputProps): ReactNode {
             <NumberInput
               label={labels[part]}
               isLabelHidden
-              // fe-app's: room for three digits of days, two of the others.
+              // Room for three digits of days, two of the others.
               width={part === "days" ? 80 : 64}
               size={size}
               min={0}

package/src/molecules/FieldGroup.doc.ts

@@ -0,0 +1,41 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for FieldGroup. */
+export const doc = {
+  category: "Layout",
+  keywords: ["fields", "group", "fieldset", "card"],
+  usage: {
+    description:
+      "Name several related fields and show a problem with the group as a whole. Use FieldRow to place a separate caption beside the grouped controls.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Supply label even without a frame, and disable child controls explicitly when using frame=card.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect isDisabled to disable the card variant; only the unframed fieldset disables its descendants.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Group label",
+        required: true,
+        description: "An accessible name, visible above content in the card variant.",
+      },
+      {
+        name: "Fields",
+        required: true,
+        description: "Host controls with the requested gap.",
+      },
+      {
+        name: "Description and error",
+        required: false,
+        description: "Help and a translated problem with the group.",
+      },
+    ],
+  },
+  accessibility: ["The unframed variant is a named fieldset; the card variant uses role group."],
+} satisfies ComponentDoc;

package/src/molecules/FieldGroup.tsx

@@ -18,7 +18,7 @@ export type FieldGroupProps = {
   readonly frame?: "none" | "card" | undefined;
   /** Help under the label. */
   readonly description?: string | undefined;
-  /** Disables every field in the group, e.g. for a read-only form. */
+  /** Disables fields through the unframed fieldset; with `frame="card"`, disable children yourself. */
   readonly isDisabled?: boolean | undefined;
   /** A problem with the group as a whole, already in the user's language. */
   readonly error?: string | undefined;

package/src/molecules/FieldRow.doc.ts

@@ -0,0 +1,36 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for FieldRow. */
+export const doc = {
+  category: "Layout",
+  keywords: ["form", "caption", "columns", "responsive"],
+  usage: {
+    description:
+      "Arrange a form section as a caption column beside its controls, stacking when room is limited. Use SideLabelRow for padded rows inside a card.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep caption widths consistent through the theme or labelWidth and use align=start for controls without a useful text baseline.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not rely on the visible caption to name individual controls; keep their own labels.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Caption column",
+        required: false,
+        description:
+          "The label and optional description; its space remains when no label is supplied in horizontal layout.",
+      },
+      {
+        name: "Control column",
+        required: true,
+        description: "Host controls that move below the caption in a narrow layout.",
+      },
+    ],
+  },
+} satisfies ComponentDoc;

package/src/molecules/FieldRow.tsx

@@ -8,7 +8,7 @@ import type { ReactNode } from "react";
 export type FieldRowProps = {
   /**
    * The row's caption, in a column at the start. Without it the column stays, empty, so the
-   * content lines up with the captioned rows around it (as fe-app's empty title column); stacked,
+   * content lines up with the captioned rows around it; stacked,
    * nothing is drawn above the content.
    */
   readonly label?: string | undefined;

package/src/molecules/FieldSkeleton.doc.ts

@@ -0,0 +1,38 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for FieldSkeleton. */
+export const doc = {
+  category: "Feedback",
+  keywords: ["field", "loading", "skeleton", "placeholder"],
+  usage: {
+    description:
+      "Reserve a form field's shape while its data loads. Use RowSkeletons for a list and ChipSkeletons for picked values.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Show the real label when known and match isLabelHidden to the field that will replace the placeholder.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not add a separate status for every skeleton inside one named loading region; set hasStatus=false.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Label",
+        required: false,
+        description: "The real caption or a short shimmer bar unless isLabelHidden.",
+      },
+      {
+        name: "Control placeholder",
+        required: true,
+        description: "A shimmer as high as a control, respecting horizontal-labels layout.",
+      },
+    ],
+  },
+  accessibility: [
+    "The default wrapper is a status named by labels.loading; hasStatus=false hides the placeholder from assistive technology.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/FrequencyLimitRow.doc.ts

@@ -0,0 +1,48 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for FrequencyLimitRow. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["frequency", "limit", "count", "window"],
+  usage: {
+    description:
+      "Edit a count per time window as one sentence. The window identified by everyWindow also reveals a number of units.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep value controlled and supply translated labels and connecting words; use paths when the inputs must be found by revealPath.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not retain every for unrelated windows; switching away from everyWindow drops that extra number.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Count input",
+        required: true,
+        description: "The number of occurrences followed by words.times.",
+      },
+      {
+        name: "Window select",
+        required: true,
+        description: "The offered counting window.",
+      },
+      {
+        name: "Every input",
+        required: false,
+        description: "An extra number and words.every for the designated window.",
+      },
+      {
+        name: "Trailing content",
+        required: false,
+        description: "Host content finishing the sentence.",
+      },
+    ],
+  },
+  accessibility: [
+    "labels.times, labels.window and labels.every supply the hidden accessible input labels.",
+  ],
+} satisfies ComponentDoc;

package/src/molecules/FrequencyLimitRow.tsx

@@ -72,7 +72,7 @@ function Marked(props: {
   );
 }
 
-// Wide enough for a few digits and the stepper, as fe-app's number box.
+// Wide enough for a few digits and the stepper.
 const TIMES_WIDTH = 80;
 
 /** "N time(s) per window" as one sentence, with a number more when the window is the `everyWindow`. */