@antscorp/ui 0.1.2 → 0.1.3

package/src/atoms/HoverSwap.doc.ts

@@ -0,0 +1,39 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for HoverSwap. */
+export const doc = {
+  category: "Layout",
+  keywords: ["hover", "actions", "focus", "row"],
+  usage: {
+    description:
+      "Share one position between resting content and row actions shown on hover or focus. Use permanent end content when the action should always be visible.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Put stylex.defaultMarker() on the ancestor row so hover and focus-within reach both layers.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not assume the transparent layer is removed from the tab order or the accessibility tree.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Resting layer",
+        required: false,
+        description: "children is visible at rest.",
+      },
+      {
+        name: "Action layer",
+        required: true,
+        description:
+          "hoverContent occupies the same grid cell and appears on ancestor hover or focus.",
+      },
+    ],
+  },
+  accessibility: [
+    "Controls in the transparent action layer remain tabbable; focusing within the marked row reveals them.",
+  ],
+} satisfies ComponentDoc;

package/src/atoms/InfoTip.doc.ts

@@ -0,0 +1,37 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for InfoTip. */
+export const doc = {
+  category: "Feedback",
+  keywords: ["help", "tooltip", "warning", "explanation"],
+  usage: {
+    description:
+      "Put a short supplementary explanation beside a control or value. Use visible error text for a problem the user must act on.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Supply a translated label explaining the nearby value; choose error tone for a warning glyph.",
+      },
+      {
+        guidance: false,
+        description: "Do not put essential instructions only in a tooltip.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Glyph",
+        required: true,
+        description: "An info icon, or a warning icon in error tone.",
+      },
+      {
+        name: "Tooltip",
+        required: false,
+        description: "The explanation supplied by label, shown on hover or keyboard focus.",
+      },
+    ],
+  },
+  accessibility: [
+    "Tab reaches the icon's wrapper, named by label, and focus opens the tooltip. Keep essential instructions visible outside it.",
+  ],
+} satisfies ComponentDoc;

package/src/atoms/InfoTip.tsx

@@ -16,8 +16,8 @@ export type InfoTipProps = {
 export function InfoTip({ label, tone = "info" }: InfoTipProps): ReactNode {
   const isError = tone === "error";
   return (
-    <Tooltip content={label}>
-      <Text as="span" color="accent" aria-label={label} xstyle={styles.info}>
+    <Tooltip content={label} focusTrigger="always">
+      <Text as="span" tabIndex={0} color="accent" aria-label={label} xstyle={styles.info}>
         <Icon icon={isError ? "warning" : "info"} size="xsm" {...(isError && { color: "error" })} />
       </Text>
     </Tooltip>

package/src/atoms/JointLabel.doc.ts

@@ -0,0 +1,23 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for JointLabel. */
+export const doc = {
+  category: "Data display",
+  keywords: ["joint", "and", "or", "rows"],
+  usage: {
+    description:
+      "Show a short connecting word between related rows. Use LabeledDivider when alternatives need a horizontal rule.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Pass the translated word in normal case and use width to align neighboring joints.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not encode rule evaluation in this label; the host owns the meaning and data.",
+      },
+    ],
+  },
+} satisfies ComponentDoc;

package/src/atoms/LabeledDivider.doc.ts

@@ -0,0 +1,35 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for LabeledDivider. */
+export const doc = {
+  category: "Layout",
+  keywords: ["separator", "divider", "alternatives", "rule"],
+  usage: {
+    description:
+      "Separate two blocks with a dashed line and a short joining word. Use JointLabel for a compact word without the rule.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Keep label short and use case to control capitalization without changing the translated text.",
+      },
+      {
+        guidance: false,
+        description: "Do not use the divider as an interactive control.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Rules",
+        required: true,
+        description: "Dashed lines extend on both sides of the word.",
+      },
+      {
+        name: "Joint word",
+        required: true,
+        description: "The centered label explains the relationship between blocks.",
+      },
+    ],
+  },
+  accessibility: ["The wrapper is a horizontal separator named by label."],
+} satisfies ComponentDoc;

package/src/atoms/LabeledDivider.tsx

@@ -7,7 +7,7 @@ import type { ReactNode } from "react";
 export type LabeledDividerProps = {
   /** The short word on the rule, such as "or"; it also names the separator. */
   readonly label: string;
-  /** `sentence` (default) shows the word as given; `upper` in capitals, as fe-app's "OR". */
+  /** `sentence` (default) shows the word as given; `upper` in capitals, such as "OR". */
   readonly case?: "sentence" | "upper" | undefined;
 };
 

package/src/atoms/LogoImage.doc.ts

@@ -0,0 +1,42 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for LogoImage. */
+export const doc = {
+  category: "Data display",
+  keywords: ["logo", "avatar", "image", "fallback"],
+  usage: {
+    description:
+      "Show a decorative logo or avatar beside content that already names it. A skeleton reserves its box until loading finishes, and fallback replaces a failed image.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Supply a fallback appropriate to the surrounding control and match size to its reserved box.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not use this decorative image to carry information that is absent from adjacent text.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Image",
+        required: false,
+        description:
+          "A lazy-loaded image in the requested square or round box, until a load failure replaces it.",
+      },
+      {
+        name: "Loading placeholder",
+        required: false,
+        description: "A matching skeleton while the image loads.",
+      },
+      {
+        name: "Fallback",
+        required: false,
+        description: "Host content shown instead of the image after a load failure.",
+      },
+    ],
+  },
+  accessibility: ["The image has an empty alt attribute; provide the identifying text elsewhere."],
+} satisfies ComponentDoc;

package/src/atoms/PanelSearchInput.doc.ts

@@ -0,0 +1,41 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for PanelSearchInput. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["search", "query", "panel", "clear"],
+  usage: {
+    description:
+      "Place a controlled search row at the top of a dropdown panel. Use SearchableGroupedList when filtering and grouped results should be composed for you.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Supply label and labels.clear, and update value on each onChange; add a Divider below when separating results.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect the input to filter data itself or provide disabled and read-only modes.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Search glyph",
+        required: true,
+        description: "A magnifier at the start or end of the row.",
+      },
+      {
+        name: "Input",
+        required: true,
+        description: "The controlled text query.",
+      },
+      {
+        name: "Clear button",
+        required: false,
+        description: "Clears a nonempty query and restores focus to the input.",
+      },
+    ],
+  },
+  accessibility: ["The input is named by label and the clear button by labels.clear."],
+} satisfies ComponentDoc;

package/src/atoms/PanelSearchInput.tsx

@@ -28,7 +28,7 @@ export type PanelSearchInputProps = {
     /** The clear button's name, such as "Clear search"; it shows only an icon. */
     readonly clear: string;
   };
-  /** Where the magnifier sits: `start` (default) or `end`, after the clear button, as fe-app's search. */
+  /** Where the magnifier sits: `start` (default) or `end`, after the clear button. */
   readonly iconPosition?: "start" | "end" | undefined;
   /** The input element, to focus it (with `useFocusLater` in a pop-over, say). */
   readonly ref?: Ref<HTMLInputElement> | undefined;

package/src/atoms/PathMark.doc.ts

@@ -0,0 +1,25 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for PathMark. */
+export const doc = {
+  category: "Layout",
+  keywords: ["path", "reveal", "focus", "form"],
+  usage: {
+    description:
+      "Mark controls so revealPath can scroll to and focus the value associated with a data path. Nested marks interpret their paths relative to the enclosing mark.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Wrap the controls of the value and use a relative path inside another PathMark.",
+      },
+      {
+        guidance: false,
+        description: "Do not expect PathMark to render a visual frame or provide a control label.",
+      },
+    ],
+  },
+  accessibility: [
+    "Keep accessible names on the wrapped controls; PathMark only carries their path for revealPath.",
+  ],
+} satisfies ComponentDoc;

package/src/atoms/RemoveButton.doc.ts

@@ -0,0 +1,26 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for RemoveButton. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["remove", "button", "row", "delete"],
+  usage: {
+    description:
+      "Offer an icon-only action to remove the surrounding row or item. Use TextAction for a removal that should have a visible text caption.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Name what will be removed through label and perform the data change in onClick.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not use isDisabled for a read-only presentation when isReadOnly should hide the removal affordance.",
+      },
+    ],
+  },
+  accessibility: [
+    "label names the icon-only button; include the item or row being removed when needed to distinguish actions.",
+  ],
+} satisfies ComponentDoc;

package/src/atoms/RowSkeletons.doc.ts

@@ -0,0 +1,43 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for RowSkeletons. */
+export const doc = {
+  category: "Feedback",
+  keywords: ["loading", "skeleton", "rows", "tiles"],
+  usage: {
+    description:
+      "Stand in for options, checkbox rows or framed picks while data loads. Use ChipSkeletons for compact picked values and FieldSkeleton for a field.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Match layout, variant, count and hasIcon to the content that will replace the placeholder.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not create multiple loading statuses inside one named load; use hasStatus=false for nested placeholders.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Text bars",
+        required: true,
+        description: "Varied shimmer widths stand in for row or tile labels.",
+      },
+      {
+        name: "Leading shape",
+        required: false,
+        description: "An icon placeholder or checkbox shape when requested.",
+      },
+      {
+        name: "End bar",
+        required: false,
+        description: "A short trailing value in check and framed variants.",
+      },
+    ],
+  },
+  accessibility: [
+    "By default the wrapper has role status, named through labels.loading; hasStatus=false hides it from assistive technology.",
+  ],
+} satisfies ComponentDoc;

package/src/atoms/TextAction.doc.ts

@@ -0,0 +1,40 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for TextAction. */
+export const doc = {
+  category: "Inputs",
+  keywords: ["action", "text", "button", "chevron"],
+  usage: {
+    description:
+      "Offer a quiet action styled as bold accent text, optionally with an icon or menu chevron. Use AddButton for an add action with the kit's plus glyph.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Pass label in normal case and let case control its appearance; omit onClick when a Popover wrapper owns activation.",
+      },
+      {
+        guidance: false,
+        description: "Do not treat this action as navigation; it renders a button without an href.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Label",
+        required: true,
+        description: "The translated action text.",
+      },
+      {
+        name: "Leading icon",
+        required: false,
+        description: "Host-supplied content before the label.",
+      },
+      {
+        name: "Chevron",
+        required: false,
+        description: "An indicator for an action that opens a menu.",
+      },
+    ],
+  },
+  accessibility: ["The text supplies the button's accessible name."],
+} satisfies ComponentDoc;

package/src/atoms/TextAction.tsx

@@ -10,7 +10,7 @@ export type TextActionProps = {
   readonly label: string;
   /** A glyph before the text, in the text's colour, such as an Astryx `Icon` of a bin for a removal. */
   readonly icon?: ReactNode;
-  /** `upper` (default) shows the label in capitals, as fe-app's "REMOVE ALL"; `sentence` as given, as fe-app's text buttons. */
+  /** `upper` (default) shows the label in capitals, such as "REMOVE ALL"; `sentence` as given. */
   readonly case?: "upper" | "sentence" | undefined;
   /**
    * Called when it is pressed. Leave it out when a wrapper handles the presses, such as an Astryx
@@ -24,8 +24,8 @@ export type TextActionProps = {
 };
 
 /**
- * An action drawn as text alone: bold capitals in the accent, no frame, as fe-app's "REMOVE ALL"
- * and "CREATE NEW … ▾", or in sentence case with a glyph before it, as fe-app's text buttons
+ * An action drawn as text alone: bold capitals in the accent, no frame, such as "REMOVE ALL"
+ * and "CREATE NEW … ▾", or in sentence case with a glyph before it
  * (a bin, then "Remove"). An Astryx `Link` without an `href`, so a `<button>` in a link's look, with
  * a down chevron after the text when it opens a menu; still a button without `onClick`, so it can
  * be a `Popover`'s trigger. It holds no state.
@@ -54,7 +54,7 @@ export function TextAction({
 }
 
 const styles = stylex.create({
-  // Capitals are a look, not text, so translations stay in normal case. fe-app's text actions have
+  // Capitals are a look, not text, so translations stay in normal case. Text actions have
   // no underline, not even on hover (Astryx's Link adds one). The theme styles no link, so this
   // sets what nothing else does.
   action: { whiteSpace: "nowrap", textDecoration: "none" },

package/src/atoms/TruncatedOption.doc.ts

@@ -0,0 +1,39 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for TruncatedOption. */
+export const doc = {
+  category: "Selection",
+  keywords: ["option", "ellipsis", "select", "label"],
+  usage: {
+    description:
+      "Render a Selector option with a one-line label and a tooltip when it is cut. Use TruncatedText for plain text outside an option.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Provide a recognizable option label; an absent label falls back to option.value.",
+      },
+      {
+        guidance: false,
+        description: "Do not expect this presentation view to own selection or open a list.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Label",
+        required: true,
+        description: "The option label, or its value, rendered through TruncatedText.",
+      },
+      {
+        name: "Icon",
+        required: false,
+        description: "The option's supplied icon.",
+      },
+      {
+        name: "Description",
+        required: false,
+        description: "Supporting option text rendered by SelectorOption.",
+      },
+    ],
+  },
+} satisfies ComponentDoc;

package/src/atoms/TruncatedOption.tsx

@@ -11,7 +11,7 @@ export type TruncatedOptionProps = {
 
 /**
  * A Selector option whose label ends in an ellipsis when it is wider than the pop-up, with the
- * whole label in a tooltip on hover, as antd's Select. Its icon and description show as the
+ * whole label in a tooltip on hover. Its icon and description show as the
  * Selector's own option's. It holds no state.
  */
 export function TruncatedOption({ option }: TruncatedOptionProps): ReactNode {

package/src/atoms/TruncatedText.doc.ts

@@ -0,0 +1,22 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for TruncatedText. */
+export const doc = {
+  category: "Data display",
+  keywords: ["text", "ellipsis", "tooltip", "overflow"],
+  usage: {
+    description:
+      "Keep a value on one line within the space its parent supplies. Astryx Text shows the whole label in a tooltip when the text is cut.",
+    bestPractices: [
+      {
+        guidance: true,
+        description: "Give the parent a constrained width so truncation has a useful boundary.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not use error tone as the only explanation of a problem; provide the reason nearby.",
+      },
+    ],
+  },
+} satisfies ComponentDoc;

package/src/doc/schema.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+
+const text = z.string().trim().min(1);
+
+/** Structured guidance beside a view; its props and examples come from TypeScript and stories. */
+export const componentDocSchema = z.object({
+  category: z
+    .enum(["Inputs", "Selection", "Feedback", "Layout", "Data display", "Overlays", "Theme"])
+    .describe(
+      "The view's purpose: Inputs edits values; Selection chooses options; Feedback communicates status; Layout arranges content; Data display presents values; Overlays shows dialogs or panels; Theme provides visual tokens and icons.",
+    ),
+  keywords: z.array(text).min(3).describe("At least three search terms for the view."),
+  related: z
+    .array(
+      z.object({
+        name: text.describe("A kit view or Astryx facade module, such as astryx/Badge."),
+        when: text.describe("When to choose this alternative."),
+      }),
+    )
+    .min(1)
+    .optional()
+    .describe(
+      "Alternatives, validated against public views and facade modules during docs generation.",
+    ),
+  example: text
+    .optional()
+    .describe("The existing story export shown first, validated during docs generation."),
+  usage: z
+    .object({
+      description: text.describe("When and how to use the view."),
+      bestPractices: z
+        .array(
+          z.object({
+            guidance: z
+              .boolean()
+              .describe("True for a recommended practice; false for a practice to avoid."),
+            description: text.describe("The practice and its reason."),
+          }),
+        )
+        .min(2)
+        .refine(
+          (items) => items.some((item) => item.guidance) && items.some((item) => !item.guidance),
+          "Include a recommended practice and a practice to avoid.",
+        )
+        .describe("Recommended practices and practices to avoid."),
+      anatomy: z
+        .array(
+          z.object({
+            name: text.describe("The part's name."),
+            required: z.boolean().describe("Whether this part is always present."),
+            description: text.describe("The part's purpose and the condition when it appears."),
+          }),
+        )
+        .min(1)
+        .optional()
+        .describe("The view's visible and interactive parts."),
+    })
+    .describe("Usage, best practices and optional anatomy."),
+  accessibility: z
+    .array(text)
+    .min(1)
+    .optional()
+    .describe("Accessible naming and interaction guidance."),
+});
+
+/** Authoring contract for a view's `<View>.doc.ts` export. */
+export type ComponentDoc = z.input<typeof componentDocSchema>;

package/src/index.ts

@@ -15,6 +15,7 @@ export { PathMark, type PathMarkProps, useEnclosingPath } from "./atoms/PathMark
 export { RowSkeletons, type RowSkeletonsProps } from "./atoms/RowSkeletons";
 export { TextAction, type TextActionProps } from "./atoms/TextAction";
 export { TruncatedText, type TruncatedTextProps } from "./atoms/TruncatedText";
+export { TruncatedOption, type TruncatedOptionProps } from "./atoms/TruncatedOption";
 export { AccentCard, type AccentCardProps } from "./molecules/AccentCard";
 export { ChoiceDialog, type ChoiceDialogProps } from "./molecules/ChoiceDialog";
 export { type ChoiceTile, ChoiceTiles, type ChoiceTilesProps } from "./molecules/ChoiceTiles";
@@ -117,3 +118,4 @@ export { HourOfDayRow, type HourOfDayRowProps } from "./organisms/HourOfDayRow";
 export { HourOfWeekGrid, type HourOfWeekGridProps } from "./organisms/HourOfWeekGrid";
 export { ResizableDrawer, type ResizableDrawerProps } from "./organisms/ResizableDrawer";
 export { TreeSelect, type TreeSelectItem, type TreeSelectProps } from "./organisms/TreeSelect";
+export { TreeSearchPanel, type TreeSearchPanelProps } from "./organisms/TreeSearchPanel";

package/src/lib/useLoadMore.ts

@@ -14,8 +14,7 @@ export type LoadMoreOptions = {
   readonly itemCount: number;
 };
 
-// fe-app loads the next page when its list is scrolled this close to the end
-// (UITargetUpdateSegment `index.jsx:719-728`).
+// Load the next page 20px before the list's end so scrolling can continue without a pause.
 const NEAR_END = "0px 0px 20px 0px";
 
 /**

package/src/lib/useLoadingShown.ts

@@ -1,7 +1,7 @@
 import { useSpinDelay } from "spin-delay";
 
 /**
- * When a loading state shows, for every view of the kit (marketinghub ADR 0080): only after the load has
+ * When a loading state shows, for every view of the kit: only after the load has
  * lasted `delay` ms, then for at least `minDuration` ms, so a fast load shows nothing and a slow
  * one never flashes. `delay` matches the antsomi theme's skeleton `animationDelay`.
  */

package/src/molecules/AccentCard.doc.ts

@@ -0,0 +1,43 @@
+import type { ComponentDoc } from "../doc/schema";
+
+/** Usage guidance for AccentCard. */
+export const doc = {
+  category: "Layout",
+  keywords: ["card", "header", "rows", "footer"],
+  usage: {
+    description:
+      "Group related rows under a titled header, with an optional close action and footer. Choose stripe or banner to match the surrounding composition.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Provide labels.close with onClose, and disable or make the supplied row controls read-only in the host.",
+      },
+      {
+        guidance: false,
+        description:
+          "Do not expect isDisabled to disable the card's children; it only blocks closing.",
+      },
+    ],
+    anatomy: [
+      {
+        name: "Header",
+        required: true,
+        description: "The title and optional named close button.",
+      },
+      {
+        name: "Rows",
+        required: true,
+        description: "Host content stacked below the header.",
+      },
+      {
+        name: "Footer",
+        required: false,
+        description: "Host content separated from the rows by a line.",
+      },
+    ],
+  },
+  accessibility: [
+    "The card is a group named by title; labels.close names its optional close button.",
+  ],
+} satisfies ComponentDoc;