@zscloud/design 0.2.0 → 0.3.1

package/dist/guidelines/design-tokens/colors.md

@@ -0,0 +1,74 @@
+# Color Tokens
+
+## Semantic color system
+
+Use semantic color names, not raw hex values. The color system adapts automatically in dark mode.
+
+### Theme (brand) colors
+
+The primary brand color. Customizable at runtime via CSS variables.
+
+| Tailwind class | CSS variable | Default |
+|---------------|-------------|---------|
+| `bg-theme-500` | `--color-theme-500` | `#0076f7` (blue) |
+| `text-theme-600` | `--color-theme-600` | Darker brand |
+| `bg-theme-50` | `--color-theme-50` | Light brand tint |
+
+Full scale: `theme-50` through `theme-950`.
+
+### Status colors
+
+| Role | Tailwind prefix | Use for | Default base |
+|------|----------------|---------|-------------|
+| **danger** | `text-danger-500` | Errors, destructive actions | `#f4454c` (red) |
+| **positive** | `text-positive-500` | Success, healthy status | `#5aca49` (green) |
+| **alert** | `text-alert-500` | Warnings, caution | `#ff9000` (orange) |
+| **info** | `text-info-500` | Informational | `#0076f7` (blue) |
+| **pending** | `text-pending-500` | In-progress, waiting | `#9a45e4` (purple) |
+
+Each status color has a full scale from `50` to `950`.
+
+### Neutral colors
+
+For text, borders, backgrounds, and disabled states.
+
+| Usage | Tailwind class | Description |
+|-------|---------------|-------------|
+| Default text | `text-neutral-700` | Primary text |
+| Secondary text | `text-neutral-500` | Muted/helper text |
+| Disabled text | `text-neutral-400` | Disabled state |
+| Default border | `border-neutral-300` | Standard borders |
+| Subtle border | `border-neutral-200` | Subtle separation |
+| Hover background | `bg-neutral-100` | Hover state |
+| Page background | `bg-neutral-50` | Light background |
+
+Full scale: `neutral-0` (white) through `neutral-950` (near-black).
+
+### On-brand color
+
+Use `text-on-brand` for text on brand-colored backgrounds (buttons, badges). This is always white.
+
+## Semantic variables (CSS)
+
+These map to component default styles:
+
+| Variable | Light mode | Purpose |
+|----------|-----------|---------|
+| `--foreground` | `neutral-700` | Default text |
+| `--background` | `white` | Page background |
+| `--primary` | `theme-600` | Primary actions |
+| `--destructive` | `red-500` | Destructive actions |
+| `--border` | `neutral-300` | Default border |
+| `--input` | `neutral-400` | Input border |
+| `--ring` | `theme-300` | Focus ring |
+| `--muted` | `neutral-100` | Muted background |
+| `--muted-foreground` | `neutral-500` | Muted text |
+
+## Rules
+
+- Always use semantic color names (`danger`, `positive`, `alert`) instead of raw color names (`red`, `green`, `orange`).
+- Use `theme-*` for brand-related elements. Do not hardcode blue.
+- Use `neutral-*` for grays. Do not use arbitrary gray values.
+- For text on colored backgrounds, use `text-on-brand` (white).
+- For hover states, go one shade darker (e.g., `bg-theme-500` hover `bg-theme-600`).
+- For disabled states, reduce to `neutral-400` text and `neutral-200` background.

package/dist/guidelines/design-tokens/shadows.md

@@ -0,0 +1,28 @@
+# Shadow Tokens
+
+## Elevation scale
+
+| Tailwind class | Use for |
+|---------------|---------|
+| `shadow-2xs` | Subtle bottom border effect |
+| `shadow-xs` | Cards at rest |
+| `shadow-sm` | Raised cards, form controls on focus |
+| `shadow-md` | Dropdowns, popovers |
+| `shadow-lg` | Dialogs, drawers |
+| `shadow-xl` | Top-level modals |
+| `shadow-2xl` | Maximum elevation |
+
+## Focus rings
+
+| Tailwind class | Use for |
+|---------------|---------|
+| `shadow-focus-ring` | Default focus indicator (green tint) |
+| `shadow-focus-ring-error` | Error state focus indicator (red tint) |
+| `shadow-focus-ring-sidebar` | Sidebar-specific focus indicator (gray) |
+
+## Rules
+
+- Use `shadow-md` for all floating elements (popovers, dropdowns, context menus).
+- Use `shadow-lg` for dialogs and drawers.
+- Do not apply shadows to flat, inline elements.
+- Focus rings are applied automatically by components. Do not manually add focus ring styles.

package/dist/guidelines/design-tokens/spacing.md

@@ -0,0 +1,46 @@
+# Spacing Tokens
+
+The spacing system follows a 4px base grid. All spacing values are multiples of 4px.
+
+## Scale
+
+| Tailwind class | Value | Common use |
+|---------------|-------|------------|
+| `gap-0.5` / `p-0.5` | 2px | Tight internal spacing |
+| `gap-1` / `p-1` | 4px | Icon-to-text gap |
+| `gap-1.5` / `p-1.5` | 6px | Compact padding |
+| `gap-2` / `p-2` | 8px | Standard gap between related items |
+| `gap-3` / `p-3` | 12px | Form field gap, card padding |
+| `gap-4` / `p-4` | 16px | Section padding, standard margin |
+| `gap-6` / `p-6` | 24px | Section separation |
+| `gap-8` / `p-8` | 32px | Large section separation |
+
+## Component-specific spacing
+
+| Context | Spacing | Example |
+|---------|---------|---------|
+| Button icon gap | `gap-1` (4px) | Icon to label inside button |
+| Form field spacing | `gap-3` (12px) | Between form items vertically |
+| Dialog body padding | `p-4` (16px) | Content area padding |
+| Card content padding | `p-4` (16px) | Card body padding |
+| Page section gap | `gap-6` (24px) | Between major sections |
+| Inline elements | `gap-2` (8px) | Between buttons in a toolbar |
+
+## Border radius
+
+| Tailwind class | Value | Use for |
+|---------------|-------|---------|
+| `rounded-none` | 0px | No rounding |
+| `rounded-xs` | 2px | Inputs, buttons, cards (default) |
+| `rounded-sm` | 4px | Tags, badges |
+| `rounded-md` | 6px | Dialogs, dropdowns |
+| `rounded-lg` | 8px | Large containers |
+| `rounded-full` | 9999px | Circular elements, pills |
+
+## Rules
+
+- Always use the 4px grid. Do not use arbitrary spacing values like 5px or 7px.
+- Use `gap-*` for flex/grid layouts instead of margin on individual children.
+- The default border radius for interactive controls is `rounded-xs` (2px). Do not override unless specifically required.
+- Use `rounded-md` (6px) for floating elements (dialogs, popovers, dropdowns).
+- Use `rounded-full` only for avatars, status dots, and pill-shaped elements.

package/dist/guidelines/design-tokens/typography.md

@@ -0,0 +1,62 @@
+# Typography Tokens
+
+## Font families
+
+| Token | Tailwind class | Value |
+|-------|---------------|-------|
+| Sans (default) | `font-sans` | `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "PingFang SC", Helvetica, Arial, sans-serif` |
+| Monospace | `font-mono` | `"SFMono-Medium", "SF Mono", "Segoe UI Mono", Menlo, Consolas, monospace` |
+
+Use `font-sans` for all UI text. Use `font-mono` only for code, UUIDs, and technical identifiers.
+
+## Font sizes
+
+| Token | Tailwind class | Size | Use for |
+|-------|---------------|------|---------|
+| xs | `text-xs` | 12px | Captions, helper text, badges |
+| sm | `text-sm` | 14px | Default body text, form labels, table cells |
+| base | `text-base` | 16px | Emphasized body text |
+| lg | `text-lg` | 20px | Section headings |
+| xl | `text-xl` | 24px | Page titles |
+| 2xl | `text-2xl` | 30px | Large headings |
+| 3xl | `text-3xl` | 38px | Hero headings |
+
+## Line heights
+
+| Token | Tailwind class | Value | Pair with |
+|-------|---------------|-------|-----------|
+| tight | `leading-tight` | 20px | `text-xs`, `text-sm` |
+| snug | `leading-snug` | 22px | `text-sm` |
+| normal | `leading-normal` | 24px | `text-base` |
+| relaxed | `leading-relaxed` | 28px | `text-lg` |
+| loose | `leading-loose` | 32px | `text-xl` |
+
+## Font weights
+
+| Tailwind class | Weight | Use for |
+|---------------|--------|---------|
+| `font-normal` | 400 | Body text |
+| `font-medium` | 500 | Labels, emphasis |
+| `font-semibold` | 600 | Headings, buttons |
+| `font-bold` | 700 | Strong emphasis |
+
+## Text component
+
+Use the `Text` component for consistent typography:
+
+```tsx
+import { Text } from "@zscloud/design"
+
+<Text variant="heading-lg">Page Title</Text>
+<Text variant="body">Regular text content</Text>
+<Text variant="caption" color="muted">Helper text</Text>
+```
+
+## Rules
+
+- The default font size for all UI controls is `text-sm` (14px). Do not use `text-xs` for form inputs or buttons.
+- Use `text-xs` (12px) only for captions, timestamps, and secondary metadata.
+- Do not use `text-base` (16px) or larger for table cell content.
+- Always pair font sizes with appropriate line heights. Use `leading-tight` for compact layouts.
+- Use `font-medium` (500) for form labels. Use `font-semibold` (600) for dialog titles and section headings.
+- Do not use letter-spacing adjustments unless specifically required for headings.

package/dist/guidelines/overview-components.md

@@ -0,0 +1,195 @@
+# Component Overview
+
+## Import pattern
+
+All components are named exports from the package root:
+
+```tsx
+import { Button, Dialog, Input, Select } from "@zscloud/design"
+```
+
+## Component categories
+
+### Form Controls
+
+| Component | Use for |
+|-----------|---------|
+| `Button` | Actions and submissions. Variants: primary, subtle, outline, secondary, danger, ghost, link |
+| `Input` | Single-line text input |
+| `InputNumber` | Numeric input with optional increment/decrement controls |
+| `InputPassword` | Password input with show/hide toggle |
+| `Textarea` | Multi-line text input |
+| `SearchInput` | Input with search icon, for filtering |
+| `Checkbox` | Boolean toggle. Supports indeterminate state |
+| `CheckboxGroup` | Multiple checkbox options |
+| `RadioGroup` | Single selection from options. Variants: basic, button |
+| `Select` | Single selection dropdown. Use `options` prop for simple usage |
+| `MultiSelect` | Multiple selection dropdown with tags |
+| `AutoComplete` | Input with suggestions dropdown |
+| `Cascader` | Hierarchical selection (province/city/district) |
+| `Switch` | Boolean toggle as a slider |
+| `Slider` | Range value selection |
+| `DatePicker` | Date selection with optional time picker |
+| `RangePicker` | Date range selection |
+| `TimePicker` | Time-only selection |
+| `Calendar` | Inline calendar display |
+| `Form` | Form container with validation. Built on react-hook-form + zod |
+
+### Data Display
+
+| Component | Use for |
+|-----------|---------|
+| `Tag` | Status labels and categories |
+| `TagList` | Multiple tags with overflow handling |
+| `Badge` | Notification count or dot indicator |
+| `StatusBadge` | Status indicator with semantic colors |
+| `Text` | Typography with variants (heading, body, caption) |
+| `Card` | Content container with header/body/footer sections |
+| `Collapse` | Expandable/collapsible content sections |
+| `Steps` | Multi-step process indicator |
+| `Progress` | Progress bar with percentage |
+| `Tree` | Hierarchical data display with expand/collapse |
+| `TreeSelect` | Tree-based selection dropdown |
+| `JsonViewer` | JSON data viewer with syntax highlighting |
+| `CodeEditor` | Code editing with syntax highlighting (CodeMirror) |
+| `Markdown` | Markdown content renderer |
+| `Divider` | Visual separator line |
+
+### Feedback
+
+| Component | Use for |
+|-----------|---------|
+| `Dialog` | Modal dialogs for confirmations, forms, and complex interactions |
+| `AlertDialog` | Simple confirm/cancel dialogs |
+| `Drawer` | Side panel overlay. Placement: right (default), left, top, bottom |
+| `Toast` | Temporary notification messages |
+| `Alert` | Inline alert messages |
+| `Spin` | Loading spinner overlay |
+| `Loader` | Inline loading indicator |
+| `PopoverConfirm` | Confirmation popover attached to a trigger |
+
+### Navigation
+
+| Component | Use for |
+|-----------|---------|
+| `Tabs` | Tab-based content switching. Variants: line, card, outline |
+| `Breadcrumb` | Navigation hierarchy |
+| `Pagination` | Page navigation with size selector |
+| `Link` | Styled anchor element |
+
+### Overlay
+
+| Component | Use for |
+|-----------|---------|
+| `Tooltip` | Hover information. 12 placement options |
+| `Popover` | Click-triggered content overlay |
+| `Dropdown` | Action menu triggered by button |
+| `ContextMenu` | Right-click context menu |
+
+### Layout
+
+| Component | Use for |
+|-----------|---------|
+| `ResizablePanelGroup` | Resizable split panes |
+| `ResizablePanel` | Individual panel within a group |
+| `ResizableHandle` | Drag handle between panels |
+
+### Business Components
+
+These are higher-level components for specific use cases:
+
+| Component | Use for |
+|-----------|---------|
+| `Field` | Labeled value display (label: value pairs) |
+| `FieldOperations` | Field with action buttons |
+| `State` | Resource state display with semantic colors |
+| `Info` | Info icon with tooltip explanation |
+| `InfoPopover` | Info icon with rich popover content |
+| `SmartTip` | Adaptive content display (truncate with expand) |
+| `Copy` | Copy-to-clipboard button |
+| `NoData` | Empty state placeholder |
+| `HeaderPage` | Page-level header with title and actions |
+| `HeaderDetail` | Detail page header with breadcrumb |
+| `HelperDoc` | Help documentation link |
+| `DateValue` | Formatted date display |
+| `ConfigProvider` | Global configuration provider |
+| `LocaleContainer` | i18n locale provider |
+| `AppBase` | Application root wrapper |
+
+## Common patterns
+
+### Form with validation
+
+```tsx
+import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage, Input, Button } from "@zscloud/design"
+import { useForm } from "react-hook-form"
+import { zodResolver } from "@hookform/resolvers/zod"
+import { z } from "zod"
+
+const schema = z.object({
+  name: z.string().min(1, "Name is required"),
+})
+
+function MyForm() {
+  const form = useForm({ resolver: zodResolver(schema) })
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)}>
+        <FormField
+          control={form.control}
+          name="name"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel required>Name</FormLabel>
+              <FormControl>
+                <Input {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit">Submit</Button>
+      </form>
+    </Form>
+  )
+}
+```
+
+### Dialog with form
+
+```tsx
+import { Dialog, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogBody, Button } from "@zscloud/design"
+
+function MyDialog({ open, onOpenChange }) {
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Edit Resource</DialogTitle>
+        </DialogHeader>
+        <DialogBody>
+          {/* Form content here */}
+        </DialogBody>
+        <DialogFooter>
+          <Button variant="subtle" onClick={() => onOpenChange(false)}>Cancel</Button>
+          <Button>Confirm</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+```
+
+### Select with options
+
+```tsx
+import { Select } from "@zscloud/design"
+
+const options = [
+  { label: "Option A", value: "a" },
+  { label: "Option B", value: "b", description: "With description" },
+]
+
+<Select options={options} value={value} onValueChange={setValue} placeholder="Select..." />
+```

package/dist/guidelines/overview-icons.md

@@ -0,0 +1,62 @@
+# Icon System
+
+The icon library provides 644 system icons and 38 app icons, all SVG-based.
+
+## Import
+
+```tsx
+import { Icon, AppIcon } from "@zscloud/design"
+```
+
+## System Icons (`Icon`)
+
+Use for inline UI icons (buttons, menus, status indicators).
+
+```tsx
+<Icon type="search" />
+<Icon type="arrow-down" />
+<Icon type="checkmark-circle-fill" color="positive" />
+<Icon type="close" color="danger" />
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `IconName` | required | Kebab-case icon name |
+| `color` | `"neutral" \| "danger" \| "positive" \| "info" \| "alert" \| "pending"` | - | Semantic color |
+| `colorNumber` | `number` | - | Color shade (50-950) |
+
+Default size: 16x16px.
+
+### Commonly used icons
+
+**Navigation**: `arrow-left`, `arrow-right`, `arrow-up`, `arrow-down`, `chevron-left`, `chevron-right`, `chevron-down`, `chevron-up`
+
+**Actions**: `add`, `close`, `delete`, `edit`, `search`, `refresh`, `download`, `upload`, `copy`, `more`, `settings`
+
+**Status**: `checkmark-circle-fill`, `close-circle-fill`, `warning-fill`, `info-circle-fill`, `loading`
+
+**Content**: `file`, `folder`, `image`, `link`, `calendar`, `clock`, `user`, `lock`, `eye`, `eye-off`
+
+## App Icons (`AppIcon`)
+
+Use for application/module navigation icons. Larger, more detailed than system icons.
+
+```tsx
+<AppIcon type="settings" />
+<AppIcon type="hardware" />
+<AppIcon type="cloud-monitoring" />
+```
+
+Default size: 40x40px.
+
+### Available app icons
+
+`backup`, `settings`, `hardware`, `cloud-monitoring`, `ai-store`, `network-resource`, `network-service`, `vcenter`, `dashboard`, `virtual-orchestration`, `storage`, `tenant-management`, `zwatch-alarm`, `zwatch-endpoint`, `zwatch-monitor-group`, `zwatch-monitor-template`, and more.
+
+## Rules
+
+- Always use the `Icon` component instead of raw SVG or icon fonts.
+- Use semantic `color` prop for status-related icons. Do not apply Tailwind color classes directly to icons.
+- Do not resize icons with `width`/`height` attributes. Use the Tailwind `size-*` class on a wrapper if needed.

package/dist/zscloud-design.es.js

@@ -19032,7 +19032,7 @@ var SelectEmptyPlaceholder = (e) => {
 });
 InputNumber.displayName = "InputNumber";
 var Pagination = (e) => {
-	let { pagination: t, setPagination: n, count: i } = e, o = useIntl(), l = Math.ceil(i / t.pageSize), [u, d] = useState(""), f = useId$1();
+	let { pagination: t, setPagination: n, count: i } = e, o = useIntl(), l = Math.ceil(i / t.pageSize), [u, d] = useState(""), f = useRef(null);
 	return /* @__PURE__ */ jsxs("div", {
 		className: "flex items-center gap-6 h-8",
 		children: [/* @__PURE__ */ jsx(PaginationRoot, {
@@ -19092,7 +19092,7 @@ var Pagination = (e) => {
 			})
 		}), /* @__PURE__ */ jsxs("div", {
 			className: "items-center text-sm flex gap-4 h-8",
-			id: `pagination-select-container-${f}`,
+			ref: f,
 			children: [/* @__PURE__ */ jsxs(SelectRoot, {
 				value: t.pageSize + "",
 				onValueChange: (e) => {
@@ -19105,7 +19105,7 @@ var Pagination = (e) => {
 					className: "w-auto text-nowrap h-8",
 					children: /* @__PURE__ */ jsx(SelectValue, {})
 				}), /* @__PURE__ */ jsx(SelectContent, {
-					selectPortalProps: { container: document.getElementById(`pagination-select-container-${f}`) },
+					selectPortalProps: { container: f.current },
 					children: /* @__PURE__ */ jsxs(SelectGroup, { children: [
 						/* @__PURE__ */ jsx(SelectItem, {
 							value: "10",
@@ -23761,34 +23761,42 @@ var cardVariants = cva("rounded-xs w-full box-border h-min bg-neutral-0", {
 	defaultVariants: { variant: "default" }
 }), CardContext = createContext({
 	isCollapsed: !1,
-	toggleCollapse: () => {}
+	toggleCollapse: () => {},
+	variant: "default"
 });
 function useCardContext() {
 	return useContext(CardContext);
 }
-function CardProvider({ children: e }) {
-	let [t, n] = useState(!1);
+function CardProvider({ children: e, variant: t }) {
+	let [n, i] = useState(!1);
 	return /* @__PURE__ */ jsx(CardContext.Provider, {
 		value: {
-			isCollapsed: t,
+			isCollapsed: n,
 			toggleCollapse: () => {
-				n(!t);
-			}
+				i(!n);
+			},
+			variant: t
 		},
 		children: e
 	});
 }
-var Card = React$1.forwardRef(({ className: e, variant: t, ...n }, i) => /* @__PURE__ */ jsx(CardProvider, { children: /* @__PURE__ */ jsx("div", {
-	ref: i,
-	className: cn(cardVariants({ variant: t }), e),
-	...n
-}) }));
-Card.displayName = "Card";
-var CardHeader = React$1.forwardRef(({ className: e, ...t }, n) => /* @__PURE__ */ jsx("div", {
-	ref: n,
-	className: cn("flex bg-transparent text-neutral-700 w-full items-center px-6 py-3 box-border justify-between border-b border-solid border-neutral-300", e),
-	...t
+var Card = React$1.forwardRef(({ className: e, variant: t, ...n }, i) => /* @__PURE__ */ jsx(CardProvider, {
+	variant: t,
+	children: /* @__PURE__ */ jsx("div", {
+		ref: i,
+		className: cn(cardVariants({ variant: t }), e),
+		...n
+	})
 }));
+Card.displayName = "Card";
+var CardHeader = React$1.forwardRef(({ className: e, ...t }, n) => {
+	let { variant: i } = useCardContext();
+	return /* @__PURE__ */ jsx("div", {
+		ref: n,
+		className: cn("flex text-neutral-700 w-full items-center box-border justify-between", i === "default" || i === "detail" || !i ? "bg-neutral-100 h-9.5 px-5" : "bg-transparent px-6 py-3", e),
+		...t
+	});
+});
 CardHeader.displayName = "CardHeader";
 var CardTitle = React$1.forwardRef(({ className: e, ...t }, n) => /* @__PURE__ */ jsx("div", {
 	ref: n,
@@ -32122,7 +32130,7 @@ var CollapseContent = React$1.forwardRef(({ className: t, forceRender: n = !1, .
 	});
 });
 CollapseContent.displayName = "CollapseContent";
-var alertVariants = cva("flex items-center relative flex-row px-4 py-2.5 rounded-xs", {
+var alertVariants = cva("flex items-start relative flex-row px-4 py-2.5 rounded-xs", {
 	variants: {
 		variant: {
 			danger: "bg-danger-50",
@@ -32152,7 +32160,7 @@ var alertVariants = cva("flex items-center relative flex-row px-4 py-2.5 rounded
 		m(!1), u == null || u();
 	}, [u]);
 	if (!p) return null;
-	let g = cn("mr-2 min-h-4 min-w-4 shrink-0", i === "weak" && "mr-1.5");
+	let g = cn("mr-2 min-h-4 min-w-4 shrink-0", i === "weak" ? "mr-1.5" : "mt-0.5");
 	return /* @__PURE__ */ jsxs("div", {
 		ref: f,
 		className: alertVariants({
@@ -32162,7 +32170,7 @@ var alertVariants = cva("flex items-center relative flex-row px-4 py-2.5 rounded
 		}),
 		...d,
 		children: [/* @__PURE__ */ jsxs("div", {
-			className: cn("text-neutral-700 text-sm flex flex-row flex-1", i === "weak" && "text-xs text-neutral-500"),
+			className: cn("text-neutral-700 text-sm flex flex-row items-start flex-1", i === "weak" && "text-xs text-neutral-500"),
 			children: [
 				n === "danger" && /* @__PURE__ */ jsx(alert_triangle_fillreact$1, { className: cn(g, "text-danger-500") }),
 				n === "warning" && /* @__PURE__ */ jsx(alert_triangle_fillreact$1, { className: cn(g, "text-alert-500") }),