@lablup/ui-common 0.1.0-alpha.9 → 0.2.0-alpha.15

package/astryx/components/PageHeader.doc.mjs

@@ -0,0 +1,94 @@
+/**
+ * `astryx component PageHeader` (and `ui-common component PageHeader`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "PageHeader",
+  displayName: "PageHeader",
+  import: "@lablup/ui-common",
+  category: "Layout",
+  keywords: ["page header", "title", "heading", "page title", "error banner", "retry"],
+  description:
+    "The top of a page: its h1 title, a description, trailing actions, and an optional error banner with Retry and dismiss. Built on Astryx Heading, Text, Banner, Button and IconButton.",
+  props: [
+    {
+      name: "title",
+      type: "string",
+      description: "Page title, rendered as the page's h1.",
+      required: true,
+    },
+    {
+      name: "description",
+      type: "string",
+      description: "Page description, below the title.",
+    },
+    {
+      name: "actions",
+      type: "ReactNode",
+      description:
+        "Actions on the trailing side; they wrap below the title when crowded.",
+    },
+    {
+      name: "error",
+      type: "string | null",
+      description: "Error message shown in a banner below the header.",
+    },
+    {
+      name: "errorDetail",
+      type: "string | null",
+      description:
+        "Secondary line under the message, for the raw detail a server returned.",
+    },
+    {
+      name: "onRetry",
+      type: "() => void",
+      description:
+        "Renders a Retry button in the error banner. Separate from dismissal, which never retries.",
+    },
+    {
+      name: "retryLabel",
+      type: "string",
+      description: "Retry button label.",
+      default: "the catalog's uic.common.retry",
+    },
+    {
+      name: "onErrorDismiss",
+      type: "() => void",
+      description: "Called when the error is dismissed; renders the dismiss button.",
+    },
+    {
+      name: "dismissErrorLabel",
+      type: "string",
+      description: "Accessible label for the dismiss button.",
+      default: 'the catalog\'s uic.PageHeader.dismissError ("Dismiss error")',
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Extra class names on the header element.",
+    },
+  ],
+  usage: {
+    description:
+      "One PageHeader per page, first inside PageLayout. Put page-level actions in `actions`; show a load or save failure in `error` rather than a separate banner.",
+    bestPractices: [
+      { guidance: true, description: "Keep the title short: it is the page's h1." },
+      {
+        guidance: true,
+        description: "Pass onRetry only when retrying is safe and idempotent.",
+      },
+      {
+        guidance: false,
+        description: "Use it inside cards or dialogs: it is the page's heading.",
+      },
+    ],
+  },
+  examples: [
+    {
+      label: "With actions and an error",
+      code: '<PageHeader\n  title="Sessions"\n  description="Running and recent compute sessions."\n  actions={<Button variant="primary" label="Start session" onClick={start} />}\n  error={error?.message}\n  onRetry={refetch}\n  onErrorDismiss={() => setError(null)}\n/>',
+    },
+  ],
+};

package/astryx/components/PageHeader.tsx

@@ -0,0 +1,3 @@
+// The Astryx CLI pairs each component doc with a same-stem source file.
+// ui-common ships no source, so this names the export instead.
+export { PageHeader } from "@lablup/ui-common";

package/astryx/components/PagedSelector.doc.mjs

@@ -0,0 +1,183 @@
+/**
+ * `astryx component PagedSelector` (and `ui-common component PagedSelector`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "PagedSelector",
+  displayName: "PagedSelector",
+  import: "@lablup/ui-common",
+  category: "Input",
+  keywords: [
+    "select",
+    "selector",
+    "infinite scroll",
+    "load more",
+    "paged",
+    "pagination",
+    "server search",
+    "async select",
+    "multi select",
+  ],
+  description:
+    "A searchable selector, single or multiple, over options loaded a page at a time: scrolling the panel near its end calls onEndReached, and search is reported per keystroke for a server-side query. Built on ComplexSelector; the panel is drawn like Selector's.",
+  props: [
+    {
+      name: "label",
+      type: "string",
+      description: "Field label and accessible name.",
+      required: true,
+    },
+    {
+      name: "options",
+      type: "PagedSelectorOption[]",
+      description:
+        "The loaded options, every page so far: { value, label, labelContent?, icon?, description?, endContent?, isDisabled? }. label is a string: the trigger text and the row's name.",
+      required: true,
+    },
+    {
+      name: "value",
+      type: "string | null | string[]",
+      description: "The selected option value; an array with isMultiple.",
+    },
+    {
+      name: "onChange",
+      type: "(value, items) => void",
+      description:
+        "Called with the new value and each chosen value's { value, label }, so labels survive values that are not on the loaded page.",
+    },
+    {
+      name: "isMultiple",
+      type: "boolean",
+      description: "Select several; the panel stays open on a pick.",
+      default: "false",
+    },
+    {
+      name: "labels",
+      type: "Record<string, string>",
+      description:
+        "Labels for selected values that may not be among options (another page, filtered out).",
+    },
+    {
+      name: "hasSearch",
+      type: "boolean",
+      description: "Search box at the top of the panel.",
+      default: "true",
+    },
+    {
+      name: "searchValue / onSearchChange",
+      type: "string / (value: string) => void",
+      description: "Controlled search text, and every keystroke; debounce it yourself.",
+    },
+    {
+      name: "onEndReached",
+      type: "() => void",
+      description:
+        "Called once each time the list is scrolled to within endReachedThreshold px of its end. Load the next page here.",
+    },
+    {
+      name: "endReachedThreshold",
+      type: "number",
+      description: "Distance from the end, in px, that counts as reaching it.",
+      default: "30",
+    },
+    {
+      name: "onAtEndChange",
+      type: "(isAtEnd: boolean) => void",
+      description: "Called when the list arrives at, or leaves, its end.",
+    },
+    {
+      name: "isLoading",
+      type: "boolean",
+      description:
+        "Spinner in the trigger; an empty list shows a loading row instead of No results.",
+    },
+    {
+      name: "isLoadingMore",
+      type: "boolean",
+      description: "Spinner in the foot while the next page loads.",
+    },
+    {
+      name: "totalCount",
+      type: "number",
+      description: 'Options in all pages; shows "Total N items" in the foot.',
+    },
+    {
+      name: "emptyText",
+      type: "ReactNode",
+      description: "Replaces the empty list's content, the loading row included.",
+    },
+    {
+      name: "header / footer",
+      type: "ReactNode / ReactNode | (close) => ReactNode",
+      description:
+        "Above and below the option list. A footer replaces the total count.",
+    },
+    {
+      name: "hasClear / onClear",
+      type: "boolean / () => void",
+      description:
+        "Clear button in the trigger; clears to null (or []) unless onClear is given.",
+    },
+    {
+      name: "triggerDisplay",
+      type: '"labels" | "badges"',
+      description:
+        'Multiple selection in the trigger: "A, B, C, +2" as MultiSelector, or tokens.',
+      default: '"labels"',
+    },
+    {
+      name: "maxTriggerItems",
+      type: "number",
+      description: "Selected items named in the trigger before +N.",
+      default: "3",
+    },
+    {
+      name: "selectionIndicator",
+      type: '"check" | "checkbox"',
+      description:
+        "The theme's check at a chosen row's end, or a checkbox at its start.",
+      default: '"check"',
+    },
+    {
+      name: "listMaxHeight",
+      type: "number",
+      description: "Height the option list scrolls within, in px.",
+      default: "260",
+    },
+    {
+      name: "placeholder, searchPlaceholder, searchLabel, clearSearchLabel, formatTotalCount",
+      type: "string / (total) => string",
+      description:
+        "Built-in strings; defaults from the uic.PagedSelector.* catalog keys.",
+    },
+    {
+      name: "isDisabled, isRequired, isOptional, description, status, size, width, onOpenChange, …",
+      type: "ComplexSelector props",
+      description: "Passed to ComplexSelector.",
+    },
+  ],
+  usage: {
+    description:
+      "For a list too long to load at once: a connection paged 10-20 rows at a time, searched on the server. For a list you hold in full, use Selector or MultiSelector.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Guard onEndReached with the connection's hasNext and in-flight state; it fires on each arrival at the end.",
+      },
+      {
+        guidance: true,
+        description:
+          "Keep each selected value's label (onChange hands it over) and pass them back in labels.",
+      },
+    ],
+  },
+  examples: [
+    {
+      label: "A paged, server-searched list",
+      code: '<PagedSelector\n  label="Owner"\n  value={ownerId}\n  onChange={(id) => setOwnerId(id)}\n  options={users.map((u) => ({ value: u.id, label: u.email }))}\n  onSearchChange={setQuery}\n  onEndReached={() => hasNext && !isLoadingNext && loadNext(10)}\n  isLoadingMore={isLoadingNext}\n  totalCount={count}\n/>',
+    },
+  ],
+};

package/astryx/components/PagedSelector.tsx

@@ -0,0 +1,3 @@
+// The Astryx CLI pairs each component doc with a same-stem source file.
+// ui-common ships no source, so this names the export instead.
+export { PagedSelector } from "@lablup/ui-common";

package/astryx/components/ProgressWithLabel.doc.mjs

@@ -0,0 +1,69 @@
+/**
+ * `astryx component ProgressWithLabel` (and `ui-common component ProgressWithLabel`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "ProgressWithLabel",
+  displayName: "ProgressWithLabel",
+  import: "@lablup/ui-common",
+  category: "Data Display",
+  keywords: ["progress", "usage bar", "resource", "labelled progress", "meter"],
+  description:
+    "A bar that carries its labels: label at the start and valueLabel at the end, over a fill of value percent, for compact resource readouts in cells and cards. A missing or NaN value draws no fill and greys the value label. The fill is color (default --color-success); the frame's corner is --progress-with-label-radius (default --radius-inner).",
+  props: [
+    {
+      name: "label",
+      type: "ReactNode",
+      description: "Start label.",
+    },
+    {
+      name: "valueLabel",
+      type: "ReactNode",
+      description: "End label.",
+    },
+    {
+      name: "value",
+      type: "number",
+      description: "Fill, in percent; above 100 fills the bar.",
+    },
+    {
+      name: "hasValueLabel",
+      type: "boolean",
+      description: "Whether the end label shows; its space stays reserved.",
+      default: "true",
+    },
+    {
+      name: "color",
+      type: "string",
+      description: "Fill colour, any CSS colour or var().",
+    },
+    {
+      name: "width",
+      type: "CSSProperties['width']",
+      description: "Bar width. Without it the bar grows in its flex container.",
+    },
+    {
+      name: "size",
+      type: "'sm' | 'md' | 'lg'",
+      description: "Label size.",
+      default: "'sm'",
+    },
+    {
+      name: "style / labelStyle",
+      type: "CSSProperties",
+      description: "Inline style of the frame / of both labels.",
+    },
+  ],
+  usage: {
+    description:
+      "Use Astryx ProgressBar for a plain progress indicator; this one is a readout whose labels sit on the bar.",
+  },
+  examples: [
+    {
+      label: "CPU usage",
+      code: '<ProgressWithLabel label="CPU" valueLabel="3 / 8" value={37.5} width={160} />',
+    },
+  ],
+};

package/astryx/components/ProgressWithLabel.tsx

@@ -0,0 +1,3 @@
+// The Astryx CLI pairs each component doc with a same-stem source file.
+// ui-common ships no source, so this names the export instead.
+export { ProgressWithLabel } from "@lablup/ui-common";

package/astryx/components/SelectionLabel.doc.mjs

@@ -0,0 +1,55 @@
+/**
+ * `astryx component SelectionLabel` (and `ui-common component SelectionLabel`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "SelectionLabel",
+  displayName: "SelectionLabel",
+  import: "@lablup/ui-common",
+  category: "Data Display",
+  keywords: ["selected", "selection", "bulk action", "deselect", "count"],
+  description:
+    '"3 selected" beside a bulk-action toolbar, with an optional button that clears the selection. Renders nothing while the count is 0.',
+  props: [
+    {
+      name: "count",
+      type: "number",
+      description: "How many items are selected.",
+      required: true,
+    },
+    {
+      name: "onClear",
+      type: "() => void",
+      description: "Clears the selection. Without it, no clear button.",
+    },
+    {
+      name: "label",
+      type: "string",
+      description: "The text.",
+      default: 'the catalog\'s uic.SelectionLabel.selectedCount ("{count} selected")',
+    },
+    {
+      name: "clearLabel",
+      type: "string",
+      description: "Accessible name and tooltip of the clear button.",
+      default: 'the catalog\'s uic.SelectionLabel.clear ("Deselect all")',
+    },
+    {
+      name: "clearIcon",
+      type: "ReactNode",
+      description: "Glyph of the clear button.",
+      default: "the theme's close icon",
+    },
+  ],
+  usage: {
+    description: "Next to the actions that apply to a table's selected rows.",
+  },
+  examples: [
+    {
+      label: "Table selection",
+      code: "<SelectionLabel count={selectedKeys.length} onClear={() => setSelectedKeys([])} />",
+    },
+  ],
+};

package/astryx/components/SelectionLabel.tsx

@@ -0,0 +1,3 @@
+// The Astryx CLI pairs each component doc with a same-stem source file.
+// ui-common ships no source, so this names the export instead.
+export { SelectionLabel } from "@lablup/ui-common";

package/astryx/components/Statistic.doc.mjs

@@ -0,0 +1,84 @@
+/**
+ * `astryx component Statistic` (and `ui-common component Statistic`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "Statistic",
+  displayName: "Statistic",
+  import: "@lablup/ui-common",
+  category: "Data Display",
+  keywords: ["metric", "statistic", "usage", "quota", "progress", "steps"],
+  description:
+    "A dashboard metric: a caption, a large value with its unit, and an optional segmented usage bar of value against total. The bar is a strip of notches with role=progressbar and a value / total tooltip. A value that is not finite shows the Unlimited label.",
+  props: [
+    {
+      name: "label",
+      type: "ReactNode",
+      description: "The caption.",
+      required: true,
+    },
+    {
+      name: "value",
+      type: "number",
+      description: "The value. Not finite renders unlimitedLabel.",
+    },
+    {
+      name: "total",
+      type: "number",
+      description: "What the value is measured against; the bar needs it.",
+    },
+    {
+      name: "unit",
+      type: "string",
+      description: "Unit after the value.",
+    },
+    {
+      name: "precision",
+      type: "number",
+      description: "Decimal places, trailing zeros dropped.",
+      default: "2",
+    },
+    {
+      name: "infinityLabel",
+      type: "string",
+      description: "A non-finite value or total in the bar's tooltip.",
+      default: "'∞'",
+    },
+    {
+      name: "progressMode",
+      type: "'hidden' | 'placeholder' | 'visible'",
+      description:
+        "visible draws the bar (with a total), placeholder keeps its space without painting it, hidden leaves it out.",
+      default: "'hidden'",
+    },
+    {
+      name: "progressSteps",
+      type: "number",
+      description: "Notches in the bar.",
+      default: "20",
+    },
+    {
+      name: "color",
+      type: "string",
+      description: "Colour of the value and of the bar's filled notches.",
+    },
+    {
+      name: "unlimitedLabel",
+      type: "string",
+      description: "Shown for a non-finite value.",
+      default: 'the catalog\'s uic.Statistic.unlimited ("Unlimited")',
+    },
+  ],
+  usage: {
+    description:
+      "A resource or quota figure on a dashboard, where the notch bar tells 3 of 20 from 4 of 20 at a glance. Other div attributes reach the root.",
+  },
+  examples: [
+    {
+      label: "Memory against its quota",
+      code: '<Statistic label="Memory" value={12} total={64} unit="GiB" progressMode="visible" />',
+    },
+  ],
+};

package/astryx/components/Statistic.tsx

@@ -0,0 +1,3 @@
+// The Astryx CLI pairs each component doc with a same-stem source file.
+// ui-common ships no source, so this names the export instead.
+export { Statistic } from "@lablup/ui-common";

package/astryx/components/StepNumberInput.doc.mjs

@@ -0,0 +1,102 @@
+/**
+ * `astryx component StepNumberInput` (and `ui-common component StepNumberInput`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "StepNumberInput",
+  displayName: "StepNumberInput",
+  import: "@lablup/ui-common",
+  category: "Inputs",
+  keywords: [
+    "number",
+    "stepper",
+    "steps",
+    "ladder",
+    "power of two",
+    "non-linear",
+    "spin",
+  ],
+  description:
+    "A number field that steps along a list of values (1, 2, 4, 8, ...) on its stepper and on ArrowUp/ArrowDown, where NumberInput steps linearly. The same module exports NumberStepper, the stepper column for an InputGroup, and getNextStepIndex, for fields that build their own stepping.",
+  props: [
+    { name: "label", type: "string", description: "Accessible name.", required: true },
+    {
+      name: "steps",
+      type: "readonly number[]",
+      description: "The values the stepper moves between.",
+      required: true,
+    },
+    { name: "value", type: "number", description: "The value, when controlled." },
+    {
+      name: "defaultValue",
+      type: "number",
+      description: "First value when uncontrolled.",
+      default: "steps[0]",
+    },
+    {
+      name: "onChange",
+      type: "(value: number) => void",
+      description: "Called with the new value. A cleared field reports 0.",
+    },
+    {
+      name: "min",
+      type: "number",
+      description: "Lower bound for typing and stepping.",
+    },
+    {
+      name: "max",
+      type: "number",
+      description: "Upper bound for typing and stepping.",
+    },
+    { name: "units", type: "string", description: 'Unit shown in the field ("GiB").' },
+    {
+      name: "isLabelHidden",
+      type: "boolean",
+      description: "Hides the label visually.",
+      default: "false",
+    },
+    { name: "placeholder", type: "string", description: "Placeholder." },
+    {
+      name: "isDisabled",
+      type: "boolean",
+      description: "Disables the field and the stepper.",
+    },
+    {
+      name: "increaseLabel",
+      type: "string",
+      description: "Accessible name of the step-up button.",
+      default: 'the catalog\'s uic.NumberStepper.increase ("Increase")',
+    },
+    {
+      name: "decreaseLabel",
+      type: "string",
+      description: "Accessible name of the step-down button.",
+      default: 'the catalog\'s uic.NumberStepper.decrease ("Decrease")',
+    },
+  ],
+  usage: {
+    description:
+      "Quantities that grow geometrically, such as sizes and counts of accelerators. For a linear step, use NumberInput with hasNumberSteppers.",
+  },
+  examples: [
+    {
+      label: "Power-of-two sizes",
+      code: `<StepNumberInput
+  label="Shared memory"
+  steps={[0.25, 0.5, 1, 2, 4, 8]}
+  units="GiB"
+  value={value}
+  onChange={setValue}
+/>`,
+    },
+    {
+      label: "The stepper alone, for a field of your own",
+      code: `<InputGroup label="Size" isLabelHidden>
+  <NumberInput label="Size" isLabelHidden value={value} onChange={setValue} />
+  <NumberStepper onStep={(direction) => setValue(nextValue(direction))} />
+</InputGroup>`,
+    },
+  ],
+};

package/astryx/components/StepNumberInput.tsx

@@ -0,0 +1,3 @@
+// The Astryx CLI pairs each component doc with a same-stem source file.
+// ui-common ships no source, so this names the export instead.
+export { StepNumberInput } from "@lablup/ui-common";

package/astryx/components/TextHighlighter.doc.mjs

@@ -0,0 +1,47 @@
+/**
+ * `astryx component TextHighlighter` (and `ui-common component TextHighlighter`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "TextHighlighter",
+  displayName: "TextHighlighter",
+  import: "@lablup/ui-common",
+  category: "Data Display",
+  keywords: ["highlight", "search", "mark", "keyword", "match"],
+  description:
+    "Marks every case-insensitive occurrence of keyword in a string, for search results. The keyword matches literally. Without a keyword the text renders plain; without text nothing renders. The mark is the theme's --color-warning-border-hover when it declares one, else --color-warning-muted.",
+  props: [
+    {
+      name: "children",
+      type: "string | null",
+      description: "The text to search in.",
+    },
+    {
+      name: "keyword",
+      type: "string",
+      description: "The text to mark.",
+    },
+    {
+      name: "highlightStyle",
+      type: "CSSProperties",
+      description: "Inline style of each mark.",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Class on the outer span.",
+    },
+  ],
+  usage: {
+    description:
+      "Inside a Token, which takes a string label, pass label={text} isLabelHidden and the highlighter as endContent, so the plain text stays the accessible name.",
+  },
+  examples: [
+    {
+      label: "A search result",
+      code: "<TextHighlighter keyword={search}>{row.name}</TextHighlighter>",
+    },
+  ],
+};

package/astryx/components/TextHighlighter.tsx

@@ -0,0 +1,3 @@
+// The Astryx CLI pairs each component doc with a same-stem source file.
+// ui-common ships no source, so this names the export instead.
+export { TextHighlighter } from "@lablup/ui-common";