@antscorp/ui 0.1.3 → 0.1.4

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;

package/src/molecules/ChoiceTiles.doc.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

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