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

package/astryx/components/CountdownBorder.doc.mjs

@@ -0,0 +1,57 @@
+/**
+ * `astryx component CountdownBorder` (and `ui-common component CountdownBorder`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "CountdownBorder",
+  displayName: "CountdownBorder",
+  import: "@lablup/ui-common",
+  category: "Feedback",
+  keywords: ["countdown", "auto refresh", "border", "timer", "progress border"],
+  description:
+    "Wraps its children in a rounded-rect border that fills clockwise over durationMs and starts again: a countdown to the next automatic refresh. It measures its own box, so the outline fits the content; the stroke is centred on the content's edge. No animation under prefers-reduced-motion. style.stroke (default var(--color-accent)), style.strokeWidth (1.5) and style.borderRadius (the theme's --radius-inner) style the border; the rest of style reaches the wrapper.",
+  props: [
+    {
+      name: "durationMs",
+      type: "number",
+      description: "Length of one fill cycle.",
+      required: true,
+    },
+    {
+      name: "isAnimated",
+      type: "boolean",
+      description: "Whether the border shows and fills.",
+      default: "true",
+    },
+    {
+      name: "resetKey",
+      type: "Key",
+      description:
+        "Restarts the fill when it changes; pass the real refresh's trigger.",
+    },
+    {
+      name: "isPaused",
+      type: "boolean",
+      description: "Freezes the fill and hides the border while a refresh runs.",
+      default: "false",
+    },
+    {
+      name: "className / style",
+      type: "string / CSSProperties",
+      description:
+        "The wrapper's class and style; see the description for the border keys.",
+    },
+  ],
+  usage: {
+    description:
+      "Wrap an auto-refresh control so the user sees when the next refresh lands. Drive resetKey and isPaused from the same state as the refresh.",
+  },
+  examples: [
+    {
+      label: "Auto-refresh button",
+      code: '<CountdownBorder durationMs={5000} resetKey={fetchKey} isPaused={isFetching}>\n  <IconButton label="Refresh" icon={<RotateCw />} onClick={refetch} />\n</CountdownBorder>',
+    },
+  ],
+};

package/astryx/components/CountdownBorder.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 { CountdownBorder } from "@lablup/ui-common";

package/astryx/components/DataGrid.doc.mjs

@@ -0,0 +1,166 @@
+/**
+ * `astryx component DataGrid` (and `ui-common component DataGrid`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "DataGrid",
+  displayName: "DataGrid",
+  import: "@lablup/ui-common",
+  category: "Data Display",
+  keywords: [
+    "data grid",
+    "table",
+    "pagination",
+    "sorting",
+    "row selection",
+    "column settings",
+    "csv export",
+    "expandable rows",
+  ],
+  description:
+    "Astryx Table with what a list page needs around it: a page bar with a range line, client or server sorting, row selection by key, resizable and pinnable columns, expandable rows, per-user column settings (visibility, order, width in one overrides record) and a CSV export picker. Rows are paged unless pagination.totalItems says they already are one page. DataGridSettingsModal and DataGridExportModal, from the same import, are its dialogs on their own. Astryx Table props it does not own (isStriped, verticalAlign, aria-*) pass through.",
+  props: [
+    {
+      name: "data",
+      type: "ReadonlyArray<T>",
+      description: "The rows.",
+    },
+    {
+      name: "columns",
+      type: "ReadonlyArray<DataGridColumn<T>>",
+      description:
+        "key, header, renderCell(item, index), width (px), minWidth, align, sortKey (sortable), compare (client sort), pin ('start' | 'end'), isAlwaysVisible, isHiddenByDefault, exportKeys, groupHeader, label, getCellProps.",
+    },
+    {
+      name: "idKey",
+      type: "string | ((item: T) => Key)",
+      description:
+        "Row identity. A missing field falls back to the row's key, then id, then position.",
+      default: "'id'",
+    },
+    {
+      name: "sort",
+      type: "DataGridSort | null",
+      description:
+        "Controlled sort, { sortKey, direction }. Columns with compare sort on the client; others only report onSortChange.",
+    },
+    {
+      name: "defaultSort",
+      type: "DataGridSort | null",
+      description: "Initial sort when uncontrolled.",
+    },
+    {
+      name: "onSortChange",
+      type: "(sort: DataGridSort | null) => void",
+      description: "Called when a header changes the sort.",
+    },
+    {
+      name: "pagination",
+      type: "false | DataGridPagination",
+      description:
+        "page, defaultPage, pageSize, defaultPageSize, totalItems, onChange(page, pageSize), hasPageSizeSelector, isHiddenOnSinglePage, endContent, plus Astryx Pagination props. false shows every row and no bar.",
+    },
+    {
+      name: "selection",
+      type: "DataGridSelection<T>",
+      description:
+        "selectedKeys (controlled), onChange(keys, items), getIsItemEnabled (select-all leaves a disabled row as it is), getRowLabel, isPreservingOtherPages.",
+    },
+    {
+      name: "columnSettings",
+      type: "DataGridColumnSettings",
+      description:
+        "Shows the settings button. overrides / defaultOverrides / onOverridesChange hold { hidden, order, width } per column key; resized widths persist there too. isReorderable (default true).",
+    },
+    {
+      name: "csvExport",
+      type: "DataGridCsvExport",
+      description:
+        "Shows the export button: supportedKeys, onExport(keys) (the dialog closes when it resolves), notice.",
+    },
+    {
+      name: "expansion",
+      type: "DataGridExpansion<T>",
+      description:
+        "renderExpandedRow, getIsRowExpandable, expandedKeys / defaultExpandedKeys / onExpandedKeysChange, columnHeader, columnWidth.",
+    },
+    {
+      name: "emptyState",
+      type: "ReactNode | false",
+      description:
+        "Shown without rows. A string gets the default icon and layout, false shows nothing.",
+      default: "the catalog's uic.DataGrid.noData",
+    },
+    {
+      name: "isLoading",
+      type: "boolean",
+      description: "Dims the rows and blocks input while data is refetched.",
+      default: "false",
+    },
+    {
+      name: "isResizable",
+      type: "boolean",
+      description: "Drag-to-resize column borders.",
+      default: "true",
+    },
+    {
+      name: "scrollWidth",
+      type: "number | string",
+      description:
+        "Scrolls horizontally with the table at this width; width-less columns size to their content.",
+    },
+    {
+      name: "maxHeight",
+      type: "number | string",
+      description: "Caps the rows' height and makes the header sticky.",
+    },
+    {
+      name: "isHeaderHidden",
+      type: "boolean",
+      description: "Hides the header row, and with it sorting and select-all.",
+      default: "false",
+    },
+    {
+      name: "getRowProps",
+      type: "(item: T, index?: number) => HTMLAttributes<HTMLTableRowElement>",
+      description: "Extra attributes for a body row.",
+    },
+    {
+      name: "density",
+      type: "'compact' | 'balanced' | 'spacious'",
+      description: "Astryx Table density.",
+      default: "'compact'",
+    },
+    {
+      name: "dividers",
+      type: "'rows' | 'columns' | 'grid' | 'none'",
+      description:
+        "Astryx Table dividers. Every value but grid adds a split between header cells.",
+      default: "'rows'",
+    },
+    {
+      name: "renderRange",
+      type: "(range: { start: number; end: number; total: number }) => ReactNode",
+      description: "The range line beside the page navigation.",
+      default: "the catalog's uic.DataGrid.range",
+    },
+    {
+      name: "expandRowLabel, invalidPageText, goToFirstPageLabel, paginationLabel, settingsLabel, exportLabel",
+      type: "string",
+      description: "Strings of the grid's chrome.",
+      default: "the catalog's uic.DataGrid.* keys",
+    },
+  ],
+  usage: {
+    description:
+      "A paged list with sorting and per-user columns. Persist columnSettings.overrides where the product keeps user settings. For server paging pass totalItems and the page's rows; for server sorting pass sort and onSortChange and leave compare off. The dialogs: DataGridSettingsModal (isOpen, onOpenChange, columns, visibleColumnKeys, isReorderable, onApply) and DataGridExportModal (isOpen, onOpenChange, columns with exportKeys, supportedKeys, onExport, notice).",
+  },
+  examples: [
+    {
+      label: "Server-paged grid with column settings",
+      code: '<DataGrid\n  data={page.items}\n  idKey="id"\n  columns={[\n    { key: "name", header: "Name", renderCell: (u) => u.name, sortKey: "name", isAlwaysVisible: true },\n    { key: "email", header: "Email", renderCell: (u) => u.email, exportKeys: ["email"] },\n  ]}\n  sort={sort}\n  onSortChange={setSort}\n  pagination={{ page, pageSize, totalItems: page.total, onChange: setPage }}\n  columnSettings={{ overrides, onOverridesChange: setOverrides }}\n/>',
+    },
+  ],
+};

package/astryx/components/DataGrid.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 { DataGrid } from "@lablup/ui-common";

package/astryx/components/DeleteConfirmModal.doc.mjs

@@ -0,0 +1,163 @@
+/**
+ * `astryx component DeleteConfirmModal` (and `ui-common component DeleteConfirmModal`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "DeleteConfirmModal",
+  displayName: "DeleteConfirmModal",
+  import: "@lablup/ui-common",
+  category: "Overlay",
+  keywords: [
+    "delete",
+    "confirm",
+    "type to confirm",
+    "destructive",
+    "irreversible",
+    "remove",
+  ],
+  description:
+    "Confirms a deletion on Modal: a warning title, a question, the items about to go and a destructive action. For several items, or with isConfirmInputRequired, the user types confirmText before the action enables. isReversible keeps the layout without the typed confirmation or the warning.",
+  props: [
+    {
+      name: "isOpen",
+      type: "boolean",
+      description: "Whether it is open.",
+      required: true,
+    },
+    {
+      name: "onOpenChange",
+      type: "(isOpen: boolean) => void",
+      description: "Called with false on Cancel, Escape and a backdrop click.",
+      required: true,
+    },
+    {
+      name: "items",
+      type: "{ key: string; label: ReactNode }[]",
+      description: "The items about to be deleted. None disables the action.",
+      required: true,
+    },
+    {
+      name: "onAction",
+      type: "() => unknown",
+      description:
+        "The deletion. A returned promise keeps the action pending. It does not close the modal.",
+      required: true,
+    },
+    {
+      name: "title",
+      type: "ReactNode",
+      description: "Title.",
+      default:
+        'the catalog\'s uic.DeleteConfirmModal.title ("Delete"), or titleMany ("Delete 3 items")',
+    },
+    {
+      name: "titleIcon",
+      type: "ReactNode",
+      description: "Glyph before the title.",
+      default: "the theme's warning icon",
+    },
+    {
+      name: "description",
+      type: "ReactNode",
+      description: "The question above the list.",
+      default: "the catalog's targetDescription with target, else description",
+    },
+    {
+      name: "target",
+      type: "ReactNode",
+      description:
+        'What kind of thing is deleted ("Project"), for the default question.',
+    },
+    {
+      name: "isReversible",
+      type: "boolean",
+      description: "No typed confirmation and no warning.",
+      default: "false",
+    },
+    {
+      name: "isConfirmInputRequired",
+      type: "boolean",
+      description: "Typed confirmation for one item too.",
+      default: "false",
+    },
+    {
+      name: "confirmText",
+      type: "string",
+      description: "What the user types. An empty string keeps the action disabled.",
+      default:
+        'the single item\'s text label, else uic.DeleteConfirmModal.confirmText ("Delete")',
+    },
+    {
+      name: "inputLabel",
+      type: "ReactNode | (confirmText: ReactNode) => ReactNode",
+      description:
+        "Label above the field; a function receives the confirm text drawn as a token.",
+      default:
+        'the catalog\'s uic.DeleteConfirmModal.typeToConfirm ("Type {confirmText} to confirm.")',
+    },
+    {
+      name: "inputPlaceholder",
+      type: "string",
+      description: "Placeholder of the field.",
+    },
+    { name: "isInputDisabled", type: "boolean", description: "Disables the field." },
+    {
+      name: "extraContent",
+      type: "ReactNode",
+      description: "Content after the field.",
+    },
+    {
+      name: "warningText",
+      type: "string",
+      description: "The irreversibility warning.",
+      default:
+        'the catalog\'s uic.DeleteConfirmModal.cannotBeUndone ("This action cannot be undone.")',
+    },
+    {
+      name: "itemListMaxHeight",
+      type: "number",
+      description: "Item list height cap in pixels; 0 for none.",
+      default: "200",
+    },
+    {
+      name: "hasPlainItems",
+      type: "boolean",
+      description: "Items without the boxed surface.",
+      default: "false",
+    },
+    {
+      name: "actionLabel",
+      type: "string",
+      description: "Action label.",
+      default: 'the catalog\'s uic.common.delete ("Delete")',
+    },
+    {
+      name: "isActionDisabled",
+      type: "boolean",
+      description: "Disables the action. It cannot open the typed-confirmation gate.",
+    },
+  ],
+  usage: {
+    description:
+      "Any permanent deletion. Pass isConfirmInputRequired and the resource name as confirmText when one item is deleted irreversibly.",
+  },
+  examples: [
+    {
+      label: "Irreversible deletion of one item",
+      code: `<DeleteConfirmModal
+  isOpen={preset != null}
+  onOpenChange={(open) => !open && setPreset(null)}
+  items={preset ? [{ key: preset.id, label: preset.name }] : []}
+  target="Preset"
+  confirmText={preset?.name ?? ""}
+  isConfirmInputRequired
+  onAction={async () => {
+    await remove(preset.id);
+    setPreset(null);
+  }}
+/>`,
+    },
+  ],
+};

package/astryx/components/DeleteConfirmModal.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 { DeleteConfirmModal } from "@lablup/ui-common";

package/astryx/components/DividedRow.doc.mjs

@@ -0,0 +1,85 @@
+/**
+ * `astryx component DividedRow` (and `ui-common component DividedRow`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "DividedRow",
+  displayName: "DividedRow",
+  import: "@lablup/ui-common",
+  category: "Layout",
+  keywords: ["divider", "separator", "wrap", "row", "stat row"],
+  description:
+    "Lays its children out in a wrapping row and draws a vertical divider between neighbours on the same line only, centred in the column gap. An item that ends a line has no divider after it; line ends are measured after layout and on every resize.",
+  props: [
+    {
+      name: "children",
+      type: "ReactNode",
+      description: "The items. Empty children are skipped.",
+    },
+    {
+      name: "wrap",
+      type: "'wrap' | 'nowrap'",
+      description: "Whether items flow onto more lines.",
+      default: "'wrap'",
+    },
+    {
+      name: "rowGap",
+      type: "number | string",
+      description: "Gap between lines. A number is pixels.",
+      default: "var(--spacing-8)",
+    },
+    {
+      name: "columnGap",
+      type: "number | string",
+      description:
+        "Gap between items on a line; the divider sits in its middle. A number is pixels.",
+      default: "var(--spacing-12)",
+    },
+    {
+      name: "dividerWidth",
+      type: "number",
+      description: "Divider thickness in pixels.",
+      default: "1",
+    },
+    {
+      name: "dividerColor",
+      type: "string",
+      description: "Divider colour.",
+      default: "var(--color-border)",
+    },
+    {
+      name: "dividerInset",
+      type: "number",
+      description:
+        "How far the divider stops short of the item's top and bottom, in pixels.",
+      default: "0",
+    },
+    {
+      name: "itemStyle",
+      type: "CSSProperties",
+      description: "Inline styles on each item's wrapper.",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Class names on the row.",
+    },
+    {
+      name: "style",
+      type: "CSSProperties",
+      description: "Inline styles on the row.",
+    },
+  ],
+  usage: {
+    description:
+      "A row of metrics or summaries that should read as separate columns and still wrap on a narrow screen.",
+  },
+  examples: [
+    {
+      label: "Metrics separated by dividers",
+      code: '<DividedRow>\n  <Statistic label="CPU" value={4} />\n  <Statistic label="Memory" value={16} unit="GiB" />\n</DividedRow>',
+    },
+  ],
+};

package/astryx/components/DividedRow.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 { DividedRow } from "@lablup/ui-common";

package/astryx/components/DoubleBadge.doc.mjs

@@ -0,0 +1,40 @@
+/**
+ * `astryx component DoubleBadge` (and `ui-common component DoubleBadge`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "DoubleBadge",
+  displayName: "DoubleBadge",
+  import: "@lablup/ui-common",
+  category: "Data Display",
+  keywords: ["badge", "pair", "welded", "status and detail", "badge group"],
+  description:
+    "A run of Astryx Badges welded into one chip, for a live pair such as a status and its detail. Neighbours overlap by one border width and square their inner corners.",
+  props: [
+    {
+      name: "values",
+      type: "Array<string | { label: string; variant?: BadgeVariant }>",
+      description:
+        "The badges, in order. A string is a neutral Badge; an empty label is skipped.",
+    },
+  ],
+  usage: {
+    description:
+      "For values the system changes on its own. An empty list renders nothing.",
+    bestPractices: [
+      { guidance: true, description: "Keep it to two or three parts." },
+      {
+        guidance: false,
+        description: "Use it for values only a user edits; weld Tokens for those.",
+      },
+    ],
+  },
+  examples: [
+    {
+      label: "Status and elapsed time",
+      code: '<DoubleBadge values={[{ label: "RUNNING", variant: "success" }, "2m"]} />',
+    },
+  ],
+};

package/astryx/components/DoubleBadge.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 { DoubleBadge } from "@lablup/ui-common";

package/astryx/components/DoubleToken.doc.mjs

@@ -0,0 +1,38 @@
+/**
+ * `astryx component DoubleToken` (and `ui-common component DoubleToken`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "DoubleToken",
+  displayName: "DoubleToken",
+  import: "@lablup/ui-common",
+  category: "Data Display",
+  keywords: ["token pair", "welded tokens", "key value", "chip", "tag pair"],
+  description:
+    "A run of Tokens welded into one chip, for a settled pair (a type and its version, a scope and its name); the live counterpart is DoubleBadge. A string value is a blue Token; empty labels are skipped. highlightKeyword marks the keyword in each label with TextHighlighter and keeps the plain label as the accessible name.",
+  props: [
+    {
+      name: "values",
+      type: "Array<string | { label: string; color?: TokenColor; endContent?: ReactNode }>",
+      description:
+        "The tokens, in order. A value's endContent replaces its visible label (the label stays the accessible name); the caller renders the label inside it, and highlightKeyword does not reach into it.",
+    },
+    {
+      name: "highlightKeyword",
+      type: "string",
+      description: "Marks this text in every label.",
+    },
+  ],
+  usage: {
+    description:
+      "Values that change only when someone edits them. A status that changes on its own is a DoubleBadge.",
+  },
+  examples: [
+    {
+      label: "A runtime and its version",
+      code: '<DoubleToken values={[{ label: "CUDA", color: "green" }, "12.4"]} />',
+    },
+  ],
+};

package/astryx/components/DoubleToken.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 { DoubleToken } from "@lablup/ui-common";