@antscorp/ui 0.1.3 → 0.1.5

package/src/atoms/ChipSkeletons.doc.ts

@@ -1,31 +0,0 @@
-import type { ComponentDoc } from "../doc/schema";
-
-/** Usage guidance for ChipSkeletons. */
-export const doc = {
-  category: "Feedback",
-  keywords: ["loading", "skeleton", "chips", "placeholder"],
-  usage: {
-    description:
-      "Reserve the shape of picked values while their labels load. Use RowSkeletons for a vertical options list.",
-    bestPractices: [
-      {
-        guidance: true,
-        description:
-          "Match count, size and shape to the values being loaded, and supply label for the loading status.",
-      },
-      {
-        guidance: false,
-        description:
-          "Do not replace already known labels with skeletons unless the whole list is being reloaded.",
-      },
-    ],
-    anatomy: [
-      {
-        name: "Chip bars",
-        required: true,
-        description: "A row of rounded shimmer bars with varied widths.",
-      },
-    ],
-  },
-  accessibility: ["The wrapper has role status and uses label as its accessible name."],
-} satisfies ComponentDoc;

package/src/atoms/FieldHeading.doc.ts

@@ -1,22 +0,0 @@
-import type { ComponentDoc } from "../doc/schema";
-
-/** Usage guidance for FieldHeading. */
-export const doc = {
-  category: "Data display",
-  keywords: ["heading", "caption", "field"],
-  usage: {
-    description:
-      "Show a separate supporting caption above controls whose own labels are hidden. Use FieldRow when the form needs a caption column beside its controls.",
-    bestPractices: [
-      {
-        guidance: true,
-        description:
-          "Keep each control's own accessible label even when FieldHeading supplies the visible caption.",
-      },
-      {
-        guidance: false,
-        description: "Do not treat this text as a label association or a semantic heading element.",
-      },
-    ],
-  },
-} satisfies ComponentDoc;

package/src/atoms/HoverSwap.doc.ts

@@ -1,39 +0,0 @@
-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

@@ -1,37 +0,0 @@
-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/JointLabel.doc.ts

@@ -1,23 +0,0 @@
-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

@@ -1,35 +0,0 @@
-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/LogoImage.doc.ts

@@ -1,42 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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/PathMark.doc.ts

@@ -1,25 +0,0 @@
-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

@@ -1,26 +0,0 @@
-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

@@ -1,43 +0,0 @@
-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

@@ -1,40 +0,0 @@
-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/TruncatedOption.doc.ts

@@ -1,39 +0,0 @@
-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/TruncatedText.doc.ts

@@ -1,22 +0,0 @@
-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/molecules/AccentCard.doc.ts

@@ -1,43 +0,0 @@
-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;

package/src/molecules/CheckGroup.doc.ts

@@ -1,40 +0,0 @@
-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

@@ -1,43 +0,0 @@
-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/ChoiceDialog.doc.ts

@@ -1,48 +0,0 @@
-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;