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

package/astryx/components/AlertModal.doc.mjs

@@ -0,0 +1,91 @@
+/**
+ * `astryx component AlertModal` (and `ui-common component AlertModal`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "AlertModal",
+  displayName: "AlertModal",
+  import: "@lablup/ui-common",
+  category: "Overlay",
+  keywords: ["alert dialog", "confirm", "alertdialog", "destructive", "are you sure"],
+  description:
+    "The WAI-ARIA alert dialog on Modal's portalled surface: role=alertdialog named by its title and described by its description, Cancel focused first, Escape cancels, the backdrop does not. ui-common hides Astryx AlertDialog in its favour: it joins Modal's level stack and leaves the notification layer reachable.",
+  props: [
+    {
+      name: "isOpen",
+      type: "boolean",
+      description: "Whether it is open.",
+      required: true,
+    },
+    {
+      name: "onOpenChange",
+      type: "(isOpen: boolean) => void",
+      description: "Called with false on Cancel and on Escape.",
+      required: true,
+    },
+    { name: "title", type: "string", description: "The question.", required: true },
+    {
+      name: "description",
+      type: "string",
+      description: "The consequence.",
+      required: true,
+    },
+    {
+      name: "actionLabel",
+      type: "string",
+      description: "Action button label.",
+      required: true,
+    },
+    {
+      name: "onAction",
+      type: "() => unknown",
+      description: "Runs on the action button. It does not close the modal.",
+      required: true,
+    },
+    {
+      name: "actionVariant",
+      type: "ButtonVariant",
+      description: "Action button variant.",
+      default: '"destructive"',
+    },
+    {
+      name: "isActionLoading",
+      type: "boolean",
+      description: "Shows the action pending.",
+    },
+    { name: "isActionDisabled", type: "boolean", description: "Disables the action." },
+    {
+      name: "cancelLabel",
+      type: "string",
+      description: "Cancel label.",
+      default: 'the catalog\'s uic.common.cancel ("Cancel")',
+    },
+    {
+      name: "isCancelDisabled",
+      type: "boolean",
+      description: "Disables the Cancel button. Escape still cancels.",
+    },
+  ],
+  usage: {
+    description:
+      "A short, blocking question before an action. For an irreversible deletion that needs typed confirmation, use DeleteConfirmModal.",
+  },
+  examples: [
+    {
+      label: "Confirm a termination",
+      code: `<AlertModal
+  isOpen={isOpen}
+  onOpenChange={setIsOpen}
+  title="Terminate session?"
+  description="Unsaved work in the session is lost."
+  actionLabel="Terminate"
+  onAction={async () => {
+    await terminate();
+    setIsOpen(false);
+  }}
+/>`,
+    },
+  ],
+};

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

package/astryx/components/BoardItemTitle.doc.mjs

@@ -0,0 +1,51 @@
+/**
+ * `astryx component BoardItemTitle` (and `ui-common component BoardItemTitle`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "BoardItemTitle",
+  displayName: "BoardItemTitle",
+  import: "@lablup/ui-common",
+  category: "Layout",
+  keywords: ["title", "panel", "dashboard", "board", "sticky", "header"],
+  description:
+    "The title row of a dashboard panel: a heading with an optional help tooltip, and actions at the end. It sticks to the top of the panel's scroll area on the surface colour, and its two groups wrap onto separate lines when the panel is narrow.",
+  props: [
+    {
+      name: "title",
+      type: "ReactNode",
+      description:
+        "The title. A string renders as a level-5 heading; a node renders as is.",
+      required: true,
+    },
+    {
+      name: "tooltip",
+      type: "ReactNode",
+      description:
+        "Help text in a tooltip beside the title. Without it, no help glyph.",
+    },
+    {
+      name: "tooltipIcon",
+      type: "ReactNode",
+      description: "Glyph of the help tooltip.",
+      default: "the theme's info icon",
+    },
+    {
+      name: "endContent",
+      type: "ReactNode",
+      description: "Actions at the end of the row.",
+    },
+  ],
+  usage: {
+    description:
+      "At the top of a dashboard panel or a board item. Other div attributes (className, style, data-*) reach the row. The --board-item-title-z property sets its z-index (default 50).",
+  },
+  examples: [
+    {
+      label: "Panel title with help and an action",
+      code: '<BoardItemTitle\n  title="Active sessions"\n  tooltip="Counts only running sessions."\n  endContent={<Button label="Refresh" />}\n/>',
+    },
+  ],
+};

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

package/astryx/components/BooleanToken.doc.mjs

@@ -0,0 +1,57 @@
+/**
+ * `astryx component BooleanToken` (and `ui-common component BooleanToken`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "BooleanToken",
+  displayName: "BooleanToken",
+  import: "@lablup/ui-common",
+  category: "Data Display",
+  keywords: ["boolean", "true false", "on off", "enabled", "token", "yes no"],
+  description:
+    "An on/off value as an Astryx Token: green for true, the default outline for false, and a fallback when the value is not a boolean.",
+  props: [
+    {
+      name: "value",
+      type: "boolean | null | undefined",
+      description: "The value.",
+      required: true,
+    },
+    {
+      name: "trueLabel",
+      type: "string",
+      description: "Label for true.",
+      default: "the catalog's uic.BooleanToken.true",
+    },
+    {
+      name: "falseLabel",
+      type: "string",
+      description: "Label for false.",
+      default: "the catalog's uic.BooleanToken.false",
+    },
+    {
+      name: "fallback",
+      type: "ReactNode",
+      description: "Rendered when the value is not a boolean.",
+      default: '"-"',
+    },
+  ],
+  usage: {
+    description: "In table cells and metadata lists that show a setting.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Name what true means (Enabled, Public) when the column title does not.",
+      },
+    ],
+  },
+  examples: [
+    {
+      label: "A setting",
+      code: '<BooleanToken value={policy.isPublic} trueLabel="Public" falseLabel="Private" />',
+    },
+  ],
+};

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

package/astryx/components/BulkEditFormItem.doc.mjs

@@ -0,0 +1,68 @@
+/**
+ * `astryx component BulkEditFormItem` (and `ui-common component BulkEditFormItem`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "BulkEditFormItem",
+  displayName: "BulkEditFormItem",
+  import: "@lablup/ui-common",
+  category: "Inputs",
+  keywords: ["bulk edit", "batch edit", "keep as is", "multiple records", "form item"],
+  description:
+    'A Form.Item for editing one field across many records. It starts as a read-only "Keep as is" placeholder (the value stays undefined, so a submit leaves every record alone); clicking or focusing it swaps in the wrapped control; hasClear adds "Clear", which sets the value to null; "Undo changes" returns to keep mode. Takes every Form.Item prop but required, and rules without required.',
+  props: [
+    {
+      name: "name",
+      type: "NamePath",
+      description: "The field the item edits.",
+      required: true,
+    },
+    {
+      name: "children",
+      type: "ReactElement",
+      description:
+        "The control. It is cloned with value/onChange, a ref (focused when editing starts) and open/onOpenChange (opened when editing starts).",
+    },
+    {
+      name: "hasClear",
+      type: "boolean",
+      description: "Offers Clear, which sets the value to null.",
+    },
+    {
+      name: "keepValueLabel",
+      type: "string",
+      description: "The placeholder in keep mode.",
+      default: 'the catalog\'s uic.BulkEditFormItem.keepAsIs ("Keep as is")',
+    },
+    {
+      name: "clearValueLabel",
+      type: "string",
+      description: "The placeholder once cleared.",
+      default: 'the catalog\'s uic.BulkEditFormItem.clear ("Clear")',
+    },
+    {
+      name: "clearLabel",
+      type: "string",
+      description: "The clear action's label.",
+      default: 'the catalog\'s uic.BulkEditFormItem.clear ("Clear")',
+    },
+    {
+      name: "undoLabel",
+      type: "string",
+      description: "The label of the action that returns to keep mode.",
+      default: 'the catalog\'s uic.BulkEditFormItem.undoChanges ("Undo changes")',
+    },
+  ],
+  usage: {
+    description:
+      "A form that edits several selected records at once, where an untouched field must not overwrite their differing values. Render it inside a Form from @lablup/ui-common/Form.",
+  },
+  examples: [
+    {
+      label: "An optional field that can be cleared on every record",
+      code: '<BulkEditFormItem name="priority" label="Priority" hasClear clearValueLabel="No priority">\n  <NumberInput label="Priority" isLabelHidden />\n</BulkEditFormItem>',
+    },
+  ],
+};

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

package/astryx/components/BulkErrorModal.doc.mjs

@@ -0,0 +1,75 @@
+/**
+ * `astryx component BulkErrorModal` (and `ui-common component BulkErrorModal`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "BulkErrorModal",
+  displayName: "BulkErrorModal",
+  import: "@lablup/ui-common",
+  category: "Overlay",
+  keywords: ["bulk", "partial failure", "error report", "failed items", "batch"],
+  description:
+    "Reports the failures of a bulk operation: a Modal with a DataGrid of the failed items, in columns the caller describes, under an optional error banner with guidance. It has no footer; the header's close button, the backdrop or Escape close it. The grid is compact with column rules, pages at ten rows and hides its page bar on one page.",
+  props: [
+    {
+      name: "columns",
+      type: "ReadonlyArray<DataGridColumn<T>>",
+      description: "How one failed item renders.",
+      required: true,
+    },
+    {
+      name: "data",
+      type: "ReadonlyArray<T>",
+      description: "One item per failure.",
+      required: true,
+    },
+    {
+      name: "idKey",
+      type: "string | ((item: T) => Key)",
+      description: "Row identity.",
+      default: "'id', then key",
+    },
+    {
+      name: "description",
+      type: "ReactNode",
+      description:
+        "Guidance in an error banner above the grid. Without it there is no banner.",
+    },
+    {
+      name: "descriptionTitle",
+      type: "ReactNode",
+      description: "The banner's title.",
+      default: "the catalog's uic.BulkErrorModal.errorOccurred",
+    },
+    {
+      name: "title",
+      type: "ReactNode",
+      description: "The modal's title.",
+      default: "an error glyph and the catalog's uic.BulkErrorModal.title",
+    },
+    {
+      name: "isOpen / onOpenChange",
+      type: "boolean / (isOpen: boolean) => void",
+      description: "Visibility, as on Modal.",
+      required: true,
+    },
+    {
+      name: "width",
+      type: "number | string",
+      description: "Modal width.",
+      default: "720",
+    },
+  ],
+  usage: {
+    description:
+      "Only for a partial failure; a wholly failed operation is one error notice. Keep the caller's form open behind it, so the user can fix the failed items and retry.",
+  },
+  examples: [
+    {
+      label: "Failed folder deletions",
+      code: '<BulkErrorModal\n  isOpen={failures.length > 0}\n  onOpenChange={(open) => !open && setFailures([])}\n  description="Fix the failed folders and try again."\n  columns={[\n    { key: "name", header: "Folder", renderCell: (f) => f.name },\n    { key: "message", header: "Error", renderCell: (f) => f.message },\n  ]}\n  data={failures}\n/>',
+    },
+  ],
+};

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

package/astryx/components/ColorPicker.doc.mjs

@@ -0,0 +1,88 @@
+/**
+ * `astryx component ColorPicker` (and `ui-common component ColorPicker`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "ColorPicker",
+  displayName: "ColorPicker",
+  import: "@lablup/ui-common",
+  category: "Inputs",
+  keywords: ["color", "colour", "picker", "hex", "swatch", "theme", "accent"],
+  description:
+    "A hex colour field: a swatch trigger with Astryx field chrome opens a Popover holding the platform's <input type=color> and a hex TextInput, and optionally a clear button. The value is #rrggbb on both edges (toHexColor also accepts #rgb, #rrggbbaa, rgb() and rgba()). onChange fires on the settled colour, not while dragging. No alpha, no presets.",
+  props: [
+    {
+      name: "value",
+      type: "string | null",
+      description: "The colour. An unparseable value renders as unset.",
+    },
+    {
+      name: "onChange",
+      type: "(hex: string) => void",
+      description:
+        "Fires with #rrggbb when the user settles on a colour: the native input's change event, or a complete hex in the field.",
+    },
+    {
+      name: "hasValueLabel",
+      type: "boolean",
+      description: "Shows the hex next to the swatch on the trigger.",
+    },
+    {
+      name: "hasClear",
+      type: "boolean",
+      description: "Offers a clear button in the popover.",
+    },
+    {
+      name: "onClear",
+      type: "() => void",
+      description: "Fires when the clear button is pressed; the popover closes.",
+    },
+    {
+      name: "isDisabled",
+      type: "boolean",
+      description: "Disables the trigger and the popover's fields.",
+    },
+    {
+      name: "label",
+      type: "string",
+      description: "Accessible name of the trigger and the colour area.",
+      default: 'the catalog\'s uic.ColorPicker.label ("Select color")',
+    },
+    {
+      name: "hexValueLabel",
+      type: "string",
+      description: "Hidden label of the hex field.",
+      default: 'the catalog\'s uic.ColorPicker.hexValue ("Hex value")',
+    },
+    {
+      name: "clearLabel",
+      type: "string",
+      description: "The clear button's label.",
+      default: 'the catalog\'s uic.ColorPicker.clear ("Clear")',
+    },
+    {
+      name: "noColorLabel",
+      type: "string",
+      description: "Shown on the trigger with hasValueLabel when there is no colour.",
+      default: 'the catalog\'s uic.ColorPicker.noColor ("No color")',
+    },
+    {
+      name: "data-testid",
+      type: "string",
+      description:
+        "Test id of the trigger; the area, hex field, clear button and value label get <id>-area, -hex, -clear and -value.",
+    },
+  ],
+  usage: {
+    description:
+      "A theme or branding setting where the colour is stored as hex and written once per choice. className and style reach the trigger.",
+  },
+  examples: [
+    {
+      label: "An accent colour that can be reset",
+      code: '<ColorPicker label="Accent" value={accent} onChange={setAccent} hasValueLabel hasClear onClear={() => setAccent(null)} />',
+    },
+  ],
+};

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

package/astryx/components/ConfirmPopover.doc.mjs

@@ -0,0 +1,99 @@
+/**
+ * `astryx component ConfirmPopover` (and `ui-common component ConfirmPopover`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "ConfirmPopover",
+  displayName: "ConfirmPopover",
+  import: "@lablup/ui-common",
+  category: "Overlay",
+  keywords: ["confirm", "popconfirm", "are you sure", "confirmation", "popover"],
+  description:
+    "A one-click confirmation anchored to its trigger: a question, an optional supporting line, Cancel and a confirm action, on Astryx Popover. Cancel takes focus first; the action may be async.",
+  props: [
+    {
+      name: "title",
+      type: "ReactNode",
+      description: "The question. A string renders as the heading line.",
+      required: true,
+    },
+    {
+      name: "description",
+      type: "ReactNode",
+      description: "Supporting line under the title.",
+    },
+    { name: "icon", type: "ReactNode", description: "Leading glyph beside the title." },
+    {
+      name: "onAction",
+      type: "(event: MouseEvent) => unknown",
+      description:
+        "Runs on confirm. A returned promise keeps the button pending; the popover closes when it resolves.",
+    },
+    {
+      name: "actionLabel",
+      type: "string",
+      description: "Confirm button label.",
+      default: 'the catalog\'s uic.common.confirm ("Confirm")',
+    },
+    {
+      name: "actionVariant",
+      type: "ButtonVariant",
+      description: "Confirm button variant; destructive for a harmful action.",
+      default: '"primary"',
+    },
+    {
+      name: "isActionDisabled",
+      type: "boolean",
+      description: "Disable the confirm button.",
+      default: "false",
+    },
+    {
+      name: "onCancel",
+      type: "(event: MouseEvent) => void",
+      description: "Runs on Cancel; the popover closes either way.",
+    },
+    {
+      name: "cancelLabel",
+      type: "string",
+      description: "Cancel button label.",
+      default: 'the catalog\'s uic.common.cancel ("Cancel")',
+    },
+    {
+      name: "label",
+      type: "string",
+      description: "Accessible name of the popover.",
+      default: "title when it is a string, else the action label",
+    },
+    {
+      name: "children",
+      type: "ReactNode | (triggerProps) => ReactNode",
+      description:
+        "The trigger, as on Popover. Use the render-prop form inside a ButtonGroup so the button stays a direct child.",
+    },
+    {
+      name: "isOpen / onOpenChange",
+      type: "boolean / (isOpen: boolean) => void",
+      description:
+        "Controlled open state; uncontrolled without isOpen. Other Popover props pass through.",
+    },
+  ],
+  usage: {
+    description:
+      "For reversible actions: deactivate, restore, reset a form, leave a shared folder.",
+    bestPractices: [
+      {
+        guidance: false,
+        description:
+          "Guard an action that cannot be undone with it; use a Modal that asks for the name to be typed.",
+      },
+    ],
+  },
+  examples: [
+    {
+      label: "A reversible, harmful action",
+      code: '<ConfirmPopover\n  title="Deactivate this key?"\n  actionLabel="Deactivate"\n  actionVariant="destructive"\n  onAction={() => deactivate(key.id)}\n>\n  <Button label="Deactivate" />\n</ConfirmPopover>',
+    },
+  ],
+};

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

package/astryx/components/CountBadge.doc.mjs

@@ -0,0 +1,93 @@
+/**
+ * `astryx component CountBadge` (and `ui-common component CountBadge`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "CountBadge",
+  displayName: "CountBadge",
+  import: "@lablup/ui-common",
+  category: "Data Display",
+  keywords: ["count", "badge", "overlay", "notification dot", "unread", "99+"],
+  description:
+    "A count or a dot overlaid on the top-end corner of its child, such as unread notices on a bell. Astryx Badge is an inline pill with no anchored form; CountBadge positions one. The overlay is a named role=status live region.",
+  props: [
+    {
+      name: "count",
+      type: "number | ReactNode",
+      description: "The number, or node, shown.",
+    },
+    {
+      name: "hasDot",
+      type: "boolean",
+      description: "A bare dot instead of the count.",
+      default: "false",
+    },
+    {
+      name: "max",
+      type: "number",
+      description: "A numeric count above this renders as `${max}+`.",
+      default: "99",
+    },
+    {
+      name: "isZeroShown",
+      type: "boolean",
+      description: "Keep the overlay when the count is 0.",
+      default: "false",
+    },
+    {
+      name: "offset",
+      type: "[number, number]",
+      description: "Pixel nudge of the overlay: +x right, +y down.",
+    },
+    {
+      name: "size",
+      type: "'sm' | 'md'",
+      description: "`sm` is a denser pill for tab rails and table headers.",
+      default: "'md'",
+    },
+    {
+      name: "label",
+      type: "string",
+      description: 'Accessible name of the overlay, e.g. "3 unread notifications".',
+    },
+    {
+      name: "variant",
+      type: "BadgeVariant",
+      description: "The Badge variant; also colours the dot.",
+      default: "'neutral'",
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      description: "The element the overlay is anchored to.",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "On the wrapper around the child, so a rule can scope the overlay.",
+    },
+  ],
+  usage: {
+    description:
+      "Wrap the element the count belongs to. A zero or missing count renders nothing.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Give it a label: a dot has no text, and a bare number rarely says what it counts.",
+      },
+      {
+        guidance: false,
+        description: "Use it for a standalone pill; that is Astryx Badge.",
+      },
+    ],
+  },
+  examples: [
+    {
+      label: "Unread notices on a button",
+      code: '<CountBadge count={unread} variant="error" label={`${unread} unread`}>\n  <IconButton icon={<Bell />} label="Notifications" />\n</CountBadge>',
+    },
+  ],
+};

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