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

package/astryx/components/Form.doc.mjs

@@ -0,0 +1,113 @@
+/**
+ * `astryx component Form` (and `ui-common component Form`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "Form",
+  displayName: "Form",
+  import: "@lablup/ui-common/Form",
+  category: "Inputs",
+  keywords: [
+    "form",
+    "form item",
+    "validation",
+    "rules",
+    "useForm",
+    "useWatch",
+    "form list",
+    "required",
+    "antd",
+  ],
+  description:
+    "A form engine with antd's form API: Form, Form.Item, Form.List, Form.ErrorList, Form.Provider, Form.useForm, Form.useWatch, Form.useFormInstance and Form.Item.useStatus, with antd's rules (required, message, validator, type, min, max, pattern, whitespace, warningOnly). Form.Item clones its child with value/onChange and renders a label, the control, the error or help line and extra text on Astryx tokens. Validation messages come from ui-common's catalog in the active Astryx locale. It keeps antd's names on purpose: it is a form-state API, so code written against antd's form moves over with an import rewrite.",
+  props: [
+    {
+      name: "form",
+      type: "FormInstance",
+      description: "The instance from Form.useForm(); one is created when omitted.",
+    },
+    {
+      name: "initialValues",
+      type: "Store",
+      description:
+        "Seeds the store once; a later change is what resetFields() restores.",
+    },
+    {
+      name: "layout",
+      type: "'horizontal' | 'vertical' | 'inline'",
+      description: "Label placement for every item.",
+      default: "'horizontal'",
+    },
+    {
+      name: "onFinish",
+      type: "(values) => void",
+      description: "Called with the values when a submit validates.",
+    },
+    {
+      name: "onFinishFailed",
+      type: "({ values, errorFields, outOfDate }) => void",
+      description: "Called when a submit fails validation.",
+    },
+    {
+      name: "onValuesChange",
+      type: "(changedValues, allValues) => void",
+      description: "Called on user edits (not on setFieldsValue).",
+    },
+    {
+      name: "requiredMark",
+      type: "boolean | 'optional' | (label, { required }) => ReactNode",
+      description:
+        "The required marker. 'optional' and a function replace the asterisk with a hint in the label.",
+    },
+    {
+      name: "labelCol",
+      type: "{ span?, offset?, flex?, className?, style? }",
+      description: "Label column in 24ths, for horizontal forms.",
+    },
+    {
+      name: "wrapperCol",
+      type: "{ span?, offset?, flex?, className?, style? }",
+      description: "Control column in 24ths, for horizontal forms.",
+    },
+    {
+      name: "size",
+      type: "'small' | 'middle' | 'large'",
+      description: "Label and control row height: --size-element-sm/md/lg.",
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      description: "Passes disabled to every control that does not set it.",
+    },
+    {
+      name: "scrollToFirstError",
+      type: "boolean | ScrollIntoViewOptions",
+      description:
+        "On a failed submit, scrolls to the first invalid item and focuses it.",
+    },
+    {
+      name: "validateMessages",
+      type: "ValidateMessages",
+      description:
+        "Message templates (${label}, ${min}, ...) that win over the catalog. FormConfigProvider sets them app-wide.",
+    },
+    {
+      name: "component",
+      type: "ElementType | false",
+      description: "The root element; false renders none.",
+      default: "'form'",
+    },
+  ],
+  usage: {
+    description:
+      "Data-entry screens whose state, validation and submit need more than a few controlled fields. Style hooks: .uic-form-item and its __label, __control, __explain-error, __extra elements, and --form-item-margin-bottom, --form-item-gap and --form-item-line-height. Help, extra and the tooltip glyph take the theme's --color-text-description when it declares one (default --color-text-secondary). A control reaches its item's status through Form.Item.useStatus() or FormItemInputContext.",
+  },
+  examples: [
+    {
+      label: "A validated form",
+      code: 'import { Form } from "@lablup/ui-common/Form";\n\nconst [form] = Form.useForm();\n\n<Form form={form} layout="vertical" onFinish={save}>\n  <Form.Item name="name" label="Name" rules={[{ required: true }]}>\n    <TextInput label="Name" isLabelHidden />\n  </Form.Item>\n</Form>',
+    },
+  ],
+};

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

package/astryx/components/IconWithTooltip.doc.mjs

@@ -0,0 +1,57 @@
+/**
+ * `astryx component IconWithTooltip` (and `ui-common component IconWithTooltip`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "IconWithTooltip",
+  displayName: "IconWithTooltip",
+  import: "@lablup/ui-common",
+  category: "Overlay",
+  keywords: ["help icon", "info icon", "tooltip", "hint", "question mark"],
+  description:
+    "A glyph that explains itself: the icon in an unstyled, focusable button wrapped in an Astryx Tooltip, named by the tooltip's text. Takes every Tooltip prop except children and anchorRef.",
+  props: [
+    { name: "icon", type: "ReactNode", description: "The glyph.", required: true },
+    {
+      name: "content",
+      type: "ReactNode",
+      description: "The tooltip; its text names the trigger.",
+      required: true,
+    },
+    {
+      name: "focusable",
+      type: "boolean",
+      description:
+        "false renders a plain span (hover only), for use inside a link or an option.",
+      default: "true",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Extra class names on the trigger.",
+    },
+    {
+      name: "style",
+      type: "CSSProperties",
+      description: "Inline styles on the trigger.",
+    },
+  ],
+  usage: {
+    description: "Next to a label or a value that needs a sentence of explanation.",
+    bestPractices: [
+      { guidance: true, description: "Keep the hint short; it is read on hover." },
+      {
+        guidance: false,
+        description: "Put information only here that a user needs to act.",
+      },
+    ],
+  },
+  examples: [
+    {
+      label: "Help glyph",
+      code: '<IconWithTooltip icon={<CircleHelp />} content="Counts running sessions only." />',
+    },
+  ],
+};

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

package/astryx/components/ImageWithFallback.doc.mjs

@@ -0,0 +1,47 @@
+/**
+ * `astryx component ImageWithFallback` (and `ui-common component ImageWithFallback`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "ImageWithFallback",
+  displayName: "ImageWithFallback",
+  import: "@lablup/ui-common",
+  category: "Media",
+  keywords: ["image", "img", "fallback", "broken image", "logo"],
+  description:
+    "An img that renders a fallback node, typically an icon, once the image fails to load. The failure is remembered per src. Astryx Avatar and Thumbnail fall back to another image; this falls back to any node.",
+  props: [
+    { name: "src", type: "string", description: "Image source.", required: true },
+    {
+      name: "alt",
+      type: "string",
+      description:
+        "Alternative text. It also names the fallback; an empty alt hides the fallback from assistive technology.",
+      required: true,
+    },
+    {
+      name: "fallbackIcon",
+      type: "ReactNode",
+      description: "Rendered once the image fails.",
+      required: true,
+    },
+  ],
+  usage: {
+    description:
+      "For small remote images, such as vendor logos, that may be missing. Every other img attribute passes through.",
+    bestPractices: [
+      {
+        guidance: true,
+        description: "Size the fallback like the image, so the row does not shift.",
+      },
+    ],
+  },
+  examples: [
+    {
+      label: "Vendor logo",
+      code: '<ImageWithFallback src={logoUrl} alt="Vendor" width={16} fallbackIcon={<Cpu size={16} />} />',
+    },
+  ],
+};

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

package/astryx/components/ListBanner.doc.mjs

@@ -0,0 +1,50 @@
+/**
+ * `astryx component ListBanner` (and `ui-common component ListBanner`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "ListBanner",
+  displayName: "ListBanner",
+  import: "@lablup/ui-common",
+  category: "Feedback",
+  keywords: ["banner", "list", "affected items", "warning list", "alert"],
+  description:
+    "An Astryx Banner whose description is a list of items, for notices such as the items a dialog will change. The list scrolls past maxHeight and is reachable by keyboard. Without a title the list takes the title slot; without items there is no list. The other Banner props pass through.",
+  props: [
+    {
+      name: "items",
+      type: "ReadonlyArray<{ key?: Key; content: ReactNode }>",
+      description: "The items.",
+      required: true,
+    },
+    {
+      name: "title",
+      type: "ReactNode",
+      description: "Say how many items there are here.",
+    },
+    {
+      name: "maxHeight",
+      type: "number | string",
+      description: "Height at which the list scrolls.",
+      default: "165",
+    },
+    {
+      name: "status",
+      type: "'info' | 'warning' | 'error' | 'success'",
+      description: "Banner status.",
+      required: true,
+    },
+  ],
+  usage: {
+    description:
+      "Inside a dialog that acts on a selection. Name the count in the title rather than in each item.",
+  },
+  examples: [
+    {
+      label: "Users about to change",
+      code: '<ListBanner\n  status="warning"\n  title={`${users.length} users will be updated`}\n  items={users.map((u) => ({ key: u.id, content: u.email }))}\n/>',
+    },
+  ],
+};

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

package/astryx/components/Modal.doc.mjs

@@ -0,0 +1,176 @@
+/**
+ * `astryx component Modal` (and `ui-common component Modal`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "Modal",
+  displayName: "Modal",
+  import: "@lablup/ui-common/Modal",
+  category: "Overlay",
+  keywords: ["modal", "dialog", "popup", "confirm", "overlay", "sheet"],
+  description:
+    "ui-common's dialog, in place of Astryx Dialog (which ui-common does not export). It takes every Dialog prop, renders into a portal so app-level notices stay above it, stacks nested modals, and lays out a header and an OK/Cancel footer when given a title, onAction or footer.",
+  props: [
+    {
+      name: "isOpen",
+      type: "boolean",
+      description: "Whether the modal is open.",
+      required: true,
+    },
+    {
+      name: "onOpenChange",
+      type: "(isOpen: boolean) => unknown",
+      description:
+        "Called when the modal asks to open or close: Escape, backdrop, the close button, Cancel.",
+      required: true,
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      description:
+        "The body. Without title, onAction or footer, the whole surface, exactly like Dialog.",
+    },
+    {
+      name: "title",
+      type: "ReactNode",
+      description: "Header title; names the dialog. Turns on the structured layout.",
+    },
+    {
+      name: "subtitle",
+      type: "string",
+      description: "Secondary line under the title.",
+    },
+    {
+      name: "onAction",
+      type: "() => unknown",
+      description:
+        "Primary action. A returned promise shows the button pending until it settles; it does not close the modal.",
+    },
+    {
+      name: "actionLabel",
+      type: "string",
+      description: "Primary action label.",
+      default: 'the catalog\'s uic.common.ok ("OK")',
+    },
+    {
+      name: "actionVariant",
+      type: "ButtonVariant",
+      description: "Primary action variant.",
+      default: "'primary'",
+    },
+    {
+      name: "isActionLoading",
+      type: "boolean",
+      description: "Shows the primary action as pending.",
+    },
+    {
+      name: "isActionDisabled",
+      type: "boolean",
+      description: "Disables the primary action.",
+    },
+    {
+      name: "actionButtonProps",
+      type: "ModalActionButtonProps",
+      description: "More props for the primary action button (type, form, icon, ...).",
+    },
+    {
+      name: "cancelLabel",
+      type: "string",
+      description: "Cancel label.",
+      default: 'the catalog\'s uic.common.cancel ("Cancel")',
+    },
+    {
+      name: "hasCancelButton",
+      type: "boolean",
+      description: "Whether the generated footer has a Cancel button.",
+      default: "true",
+    },
+    {
+      name: "footer",
+      type: "ReactNode | null",
+      description: "Replaces the generated footer; null removes it.",
+    },
+    {
+      name: "hasCloseButton",
+      type: "boolean",
+      description: "Whether the header shows a close button.",
+      default: "true",
+    },
+    {
+      name: "headerClassName",
+      type: "string",
+      description:
+        "Class name on the generated header, for a product's own header geometry.",
+    },
+    {
+      name: "footerClassName",
+      type: "string",
+      description: "Class name on the generated footer.",
+    },
+    {
+      name: "headerStartContent",
+      type: "ReactNode",
+      description: "Content before the title, e.g. a back button.",
+    },
+    {
+      name: "headerEndContent",
+      type: "ReactNode",
+      description: "Content after the title, before the close button.",
+    },
+    {
+      name: "isLoading",
+      type: "boolean",
+      description: "Shows a text skeleton in place of the body.",
+    },
+    {
+      name: "unmountOnClose",
+      type: "boolean",
+      description: "Unmount the content, and drop its state, when the modal closes.",
+    },
+    {
+      name: "afterOpenChange",
+      type: "(isOpen: boolean) => void",
+      description: "Called right after isOpen changes, never on mount.",
+    },
+    {
+      name: "zIndex",
+      type: "number",
+      description:
+        "Asks for a z-index inside the modal band; a later modal still stacks above.",
+    },
+    {
+      name: "width | maxHeight | position | variant | purpose | padding",
+      type: "Dialog props",
+      description:
+        "As on Astryx Dialog: `ui-common astryx component Dialog` lists them.",
+    },
+  ],
+  usage: {
+    description:
+      "Use Modal wherever Astryx documentation says Dialog: a Dialog call site moves over by renaming the import. Pass title and onAction for a standard confirm/edit dialog, or children alone for a custom surface.",
+    bestPractices: [
+      {
+        guidance: true,
+        description: "Import it from @lablup/ui-common/Modal (or the root).",
+      },
+      {
+        guidance: true,
+        description:
+          "Close the modal yourself when onAction's work succeeds: onAction does not close it.",
+      },
+      {
+        guidance: false,
+        description:
+          "Import Dialog: ui-common hides it so every product has one dialog surface.",
+      },
+    ],
+  },
+  examples: [
+    {
+      label: "Rename dialog",
+      code: '<Modal\n  isOpen={isOpen}\n  onOpenChange={setIsOpen}\n  title="Rename folder"\n  actionLabel="Rename"\n  onAction={async () => {\n    await rename();\n    setIsOpen(false);\n  }}\n>\n  <TextInput label="Name" value={name} onChange={setName} />\n</Modal>',
+    },
+  ],
+};

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

package/astryx/components/NotificationItem.doc.mjs

@@ -0,0 +1,52 @@
+/**
+ * `astryx component NotificationItem` (and `ui-common component NotificationItem`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "NotificationItem",
+  displayName: "NotificationItem",
+  import: "@lablup/ui-common",
+  category: "Feedback",
+  keywords: ["notification", "notice", "toast body", "footer", "timestamp"],
+  description:
+    "The body of one notice: a title, a description, actions and a footer, stacked, with the actions and the footer at the end. A string or number in a slot renders as body Text; a node renders as is. The title leaves room for the notice's close button.",
+  props: [
+    {
+      name: "title",
+      type: "ReactNode",
+      description: "The title.",
+    },
+    {
+      name: "description",
+      type: "ReactNode",
+      description: "The description.",
+    },
+    {
+      name: "action",
+      type: "ReactNode",
+      description: "Actions, at the end of their own row.",
+    },
+    {
+      name: "footer",
+      type: "ReactNode",
+      description: "A quiet note at the end, such as when the notice arrived.",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Class names on the root.",
+    },
+  ],
+  usage: {
+    description:
+      "As the description of a NotificationStack notice whose body has more structure than a line of text.",
+  },
+  examples: [
+    {
+      label: "A finished upload",
+      code: '<NotificationItem\n  title="Upload finished"\n  description="report.csv"\n  action={<Button label="Open" />}\n  footer="2 minutes ago"\n/>',
+    },
+  ],
+};

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

package/astryx/components/NotificationStack.doc.mjs

@@ -0,0 +1,66 @@
+/**
+ * `astryx component NotificationStack` (and `ui-common component NotificationStack`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "NotificationStack",
+  displayName: "NotificationStack",
+  import: "@lablup/ui-common",
+  category: "Feedback",
+  keywords: [
+    "notification",
+    "notices",
+    "toast",
+    "background task",
+    "progress",
+    "retry",
+  ],
+  description:
+    "Floating notices stacked in the bottom-end corner, each an Astryx Banner that can carry background-task progress, Cancel/Retry and a navigation action, and a collapsible detail. Presentational: the caller owns the list and updates a notice in place under its key. Auto-close pauses on hover and focus; notices slide in and out.",
+  props: [
+    {
+      name: "notifications",
+      type: "Array<NotificationStackItem>",
+      description:
+        "Oldest first. An item takes key, title, description, status, percent, isProgressIndeterminate, progressLabel, actionText/onAction, retryText/onRetry, cancelText/onCancel, duration (seconds; null or 0 stays open), isClosable, icon, content (replaces the header) and children (collapsible detail).",
+      required: true,
+    },
+    {
+      name: "onClose",
+      type: "(key: Key) => void",
+      description: "Fired by the close button and by auto-close.",
+    },
+    {
+      name: "maxVisible",
+      type: "number",
+      description: "Cap on visible notices; the newest win.",
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Extra class names on the stack.",
+    },
+  ],
+  usage: {
+    description:
+      "Mount one per app. Set --notification-stack-z to fit your layer ladder (default 11000, above Modal's band) and --notification-stack-inset-top to keep a header clear.",
+    bestPractices: [
+      {
+        guidance: true,
+        description: "Update a running task's notice in place under the same key.",
+      },
+      {
+        guidance: false,
+        description: "Use it for a one-line confirmation; that is Astryx Toast.",
+      },
+    ],
+  },
+  examples: [
+    {
+      label: "An upload in progress",
+      code: '<NotificationStack\n  notifications={[{ key: "upload", title: "Uploading", percent: 40, onCancel: cancel }]}\n  onClose={remove}\n/>',
+    },
+  ],
+};

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

package/astryx/components/OverlayScrollbar.doc.mjs

@@ -0,0 +1,49 @@
+/**
+ * `astryx component OverlayScrollbar` (and `ui-common component OverlayScrollbar`).
+ *
+ * @type {import('@astryxdesign/cli/authoring').ComponentDoc}
+ */
+export default {
+  type: "component",
+  name: "OverlayScrollbar",
+  displayName: "OverlayScrollbar",
+  import: "@lablup/ui-common",
+  category: "Layout",
+  keywords: ["scrollbar", "overlay scrollbar", "scroll thumb", "scrollbar gutter"],
+  description:
+    "A persistent, draggable scroll thumb painted over a scroll container instead of beside it, so becoming scrollable never changes the content width. It hides the target's native bar (data-uic-overlay-scrollbar) on pointer-driven platforms and renders nothing on touch-primary ones. Updates write to the DOM, outside React's render loop.",
+  props: [
+    {
+      name: "targetRef",
+      type: "RefObject<HTMLElement | null>",
+      description: "The scroll container the thumb tracks.",
+      required: true,
+    },
+    {
+      name: "className",
+      type: "string",
+      description: "Extra class names on the track.",
+    },
+  ],
+  usage: {
+    description:
+      "Render it inside the target's positioned ancestor. Raise --overlay-scrollbar-z (default 1) to clear sticky chrome inside the column.",
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          "Use it on a page's main scroll column, where a shifting width is noticed.",
+      },
+      {
+        guidance: false,
+        description: "Put it on every small scroll area; ScrollableArea covers those.",
+      },
+    ],
+  },
+  examples: [
+    {
+      label: "A scroll column",
+      code: '<div style={{ position: "relative", height: "100%" }}>\n  <div ref={scrollRef} style={{ overflow: "auto", height: "100%" }}>{content}</div>\n  <OverlayScrollbar targetRef={scrollRef} />\n</div>',
+    },
+  ],
+};

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