@yh-ui/yh-ui-skill 1.0.38 → 1.0.42

package/assets/skills/yh-ui/references/recipes-flow.md

@@ -1,56 +1,162 @@
-# Deep Recipe: Flow
+# Deep Recipe: Flow Editor
 
-Use this recipe for workflow editors, node graphs, BPMN-like diagrams, AI workflow canvases, and visual automation builders.
+Use this recipe when building visual workflow editors, node graph layouts, BPMN diagram canvases, AI agent workflow charts, or visual automation tools.
 
 ## Default Choice
 
-Use `@yh-ui/flow` with `Flow`, `Controls`, `Minimap`, and `FlowBackground`.
+Use `@yh-ui/flow` with the core `Flow` canvas, complemented by helper components like `Controls`, `Minimap`, and `FlowBackground`.
 
-Always set an explicit canvas height.
+## Custom Node & Edge Types
 
-## Source-Aligned API Highlights
+- **BPMN Nodes**: Call `registerBpmnNodes()` to enable elements like `BpmnStartEvent`, `BpmnEndEvent`, `BpmnTask`, `BpmnServiceTask`, `BpmnUserTask`, `BpmnExclusiveGateway`, and gateway routes.
+- **AI Workflow Nodes**: Call `registerAiWorkflowNodes()` to enable AI building blocks like `AiLlmNode`, `AiPromptNode`, `AiAgentNode`, `AiToolNode`, `AiConditionNode`, `AiStartNode`, and `AiMemoryNode`.
+- **Custom Editor Helpers**: Use `NodeResizer` (for interactive sizing anchors), `NodeToolbar` (message actions above nodes), and `NodeEditPanel` for sidebar updates.
 
-- Props: `nodes`, `edges`, `modelValue`, `minZoom`, `maxZoom`, `defaultNodeType`, `defaultEdgeType`, `nodesDraggable`, `edgesConnectable`, `selectable`, `background`, `snapToGrid`, `readonly`, `keyboardShortcuts`, `showControls`, `showMinimap`, `history`, `virtualized`, `isValidConnection`.
-- Events: `update:modelValue`, `update:nodes`, `update:edges`, `nodeClick`, `nodeDragStart`, `nodeDrag`, `nodeDragEnd`, `edgeClick`, `edgeConnect`, `selectionChange`, `historyChange`, `viewportChange`.
-- Slots: `node`, `edge`.
-- Use AI workflow nodes: `AiLlmNode`, `AiPromptNode`, `AiAgentNode`, `AiToolNode`, `AiConditionNode`, `AiStartNode`, `AiEndNode`, `AiMemoryNode`.
-- Use BPMN nodes: `BpmnStartEvent`, `BpmnEndEvent`, `BpmnTask`, `BpmnServiceTask`, `BpmnUserTask`, `BpmnExclusiveGateway`, `BpmnParallelGateway`, `BpmnInclusiveGateway`.
+## Pattern: Interactive AI Agent Flow Editor
 
-## Pattern: Nuxt AI Workflow
+This example showcases a full-featured flow editor with auto-alignment guides, grid snap, interactive node resizing, history management (undo/redo), and AI workflow preset registration:
 
 ```vue
 <script setup lang="ts">
-import { Controls, Flow, FlowBackground, Minimap } from '@yh-ui/flow'
-import type { Edge, Node } from '@yh-ui/flow'
-
-const nodes: Node[] = [
-  { id: 'start', type: 'ai-start', label: 'Start', position: { x: 80, y: 120 } },
-  { id: 'llm', type: 'ai-llm', label: 'LLM', position: { x: 320, y: 120 } },
-  { id: 'end', type: 'ai-end', label: 'End', position: { x: 560, y: 120 } }
-]
-
-const edges: Edge[] = [
-  { id: 'e-start-llm', source: 'start', target: 'llm' },
-  { id: 'e-llm-end', source: 'llm', target: 'end' }
-]
+import { ref } from 'vue'
+import {
+  Flow,
+  Controls,
+  Minimap,
+  FlowBackground,
+  registerAiWorkflowNodes,
+  NodeResizer,
+  NodeToolbar,
+  type FlowNode,
+  type FlowEdge
+} from '@yh-ui/flow'
+import { YhButton, YhMessage } from '@yh-ui/components'
+
+// 1. Register AI Workflow node presets on the engine
+registerAiWorkflowNodes()
+
+// 2. Setup nodes state
+const nodes = ref<FlowNode[]>([
+  {
+    id: 'node-start',
+    type: 'ai-start',
+    label: 'Trigger Prompt',
+    position: { x: 100, y: 150 }
+  },
+  {
+    id: 'node-llm',
+    type: 'ai-llm',
+    label: 'Process text (DeepSeek)',
+    position: { x: 350, y: 150 },
+    // Custom data parameters
+    data: { model: 'deepseek-chat', temperature: 0.7 }
+  },
+  {
+    id: 'node-end',
+    type: 'ai-end',
+    label: 'Output Result',
+    position: { x: 600, y: 150 }
+  }
+])
+
+// 3. Setup edges state
+const edges = ref<FlowEdge[]>([
+  { id: 'e-start-llm', source: 'node-start', target: 'node-llm', type: 'smooth' },
+  { id: 'e-llm-end', source: 'node-llm', target: 'node-end', type: 'bezier' }
+])
+
+const flowRef = ref<any>(null)
+
+// History management helpers
+function triggerUndo() {
+  if (flowRef.value?.history) {
+    flowRef.value.history.undo()
+    YhMessage.info('Action undone')
+  }
+}
+
+function triggerRedo() {
+  if (flowRef.value?.history) {
+    flowRef.value.history.redo()
+    YhMessage.info('Action redone')
+  }
+}
+
+function handleNodeClick(node: FlowNode) {
+  console.log('Clicked node config:', node.data)
+}
 </script>
 
 <template>
-  <ClientOnly>
-    <Flow :nodes="nodes" :edges="edges" fit-view style="height: 640px">
-      <Minimap />
-      <Controls />
-      <FlowBackground />
-    </Flow>
-  </ClientOnly>
+  <div class="editor-layout">
+    <div class="editor-header">
+      <YhButton size="small" icon="mdi:undo" @click="triggerUndo">Undo</YhButton>
+      <YhButton size="small" icon="mdi:redo" @click="triggerRedo">Redo</YhButton>
+    </div>
+
+    <!-- Explicit container dimensions are mandatory for Flow to compute sizes -->
+    <div class="canvas-container" style="height: 600px; border: 1px solid var(--yh-border-color)">
+      <Flow
+        ref="flowRef"
+        v-model:nodes="nodes"
+        v-model:edges="edges"
+        snap-to-grid
+        show-alignment-guides
+        :min-zoom="0.2"
+        :max-zoom="4"
+        :history="true"
+        @nodeClick="handleNodeClick"
+      >
+        <Minimap />
+        <Controls />
+        <FlowBackground color="#ccc" :grid-size="15" />
+
+        <!-- Custom slot overriding for customized node presentation -->
+        <template #node="{ node }">
+          <div class="custom-node-body">
+            <!-- NodeToolbar renders edit controls above the active node -->
+            <NodeToolbar :visible="node.selected" position="top">
+              <button class="node-action-btn">Configure</button>
+            </NodeToolbar>
+
+            <!-- NodeResizer renders adjustment handles around the box -->
+            <NodeResizer :min-width="100" :min-height="40" />
+
+            <div class="node-label">{{ node.label }}</div>
+          </div>
+        </template>
+      </Flow>
+    </div>
+  </div>
 </template>
+
+<style scoped>
+.canvas-container {
+  background-color: var(--yh-bg-color-page);
+}
+.custom-node-body {
+  padding: 10px;
+  border-radius: var(--yh-border-radius-base);
+  border: 1px solid var(--yh-border-color);
+  background: var(--yh-bg-color);
+  box-shadow: var(--yh-box-shadow-light);
+  min-width: 150px;
+}
+.node-action-btn {
+  background: var(--yh-color-primary);
+  color: #fff;
+  border: none;
+  font-size: 11px;
+  border-radius: 4px;
+  cursor: pointer;
+  padding: 2px 6px;
+}
+</style>
 ```
 
 ## Agent Rules
 
-- In Nuxt or SSR, wrap in `<ClientOnly>`.
-- Use serializable node `data` for persistence.
-- Use `isValidConnection` for business validation.
-- Use `update:nodes` and `update:edges` for controlled editing.
-- Use slots for custom node/edge rendering.
-- Do not render Flow in a zero-height container.
+- **Explicit Height**: Always wrap the `Flow` canvas inside a container element with an explicit CSS height (e.g. `style="height: 600px"`). Flow cannot render inside collapsed grid elements.
+- **ClientOnly in Nuxt**: Because flow editors heavily access browser SVG methods, always wrap `Flow` in `<ClientOnly>` when building Nuxt SSR applications.
+- **Controlled Models**: Bind canvas state using Vue 3 two-way models `v-model:nodes` and `v-model:edges` to guarantee changes propagate between component nodes and state.
+- **Durable data properties**: Save custom node parameter fields (like database queries, API targets) inside the serializable `node.data` object.

package/assets/skills/yh-ui/references/recipes-form-schema.md

@@ -1,82 +1,187 @@
 # Deep Recipe: YhFormSchema
 
-Use this recipe for schema-driven forms, dynamic business forms, generated forms, and admin create/edit pages with conditional fields.
+Use this recipe when building complex forms generated dynamically from schemas, including repeating item lists, custom field renderers, layout grids, or conditional field visibility/dependencies.
 
 ## Default Choice
 
-Use `YhFormSchema` when fields are generated from configuration or when the form needs dynamic visibility, async options, grouped fields, list fields, or custom field rendering.
+Use `YhFormSchema` when forms are configuration-driven, require repeating group elements, or need layout grid scaling. Use `YhForm` + `YhFormItem` only for simple static fields.
 
-Use `YhForm` + `YhFormItem` for small hand-written forms.
+## Schema Item Configurations
 
-## Source-Aligned API Highlights
+Each field schema object supports:
 
-- Props: `modelValue`, `schema`, `formProps`, `gutter`.
-- Events: `update:modelValue`, `submit`, `change`, `validate`.
-- Schema item capabilities: `field`, `label`, `type`, `component`, `props`, `formItemProps`, `rules`, `required`, `hidden`, `disabled`, `slots`, `col`, `span`, `render`, `asyncOptions`, `optionProp`, `defaultValue`, `tooltip`.
-- Special item types: `divider`, `text`, `list`.
-- Expose: `validate`, `resetFields`, `clearValidate`, `scrollToField`, `getModel`, `setFieldValue`, `formRef`.
+- `field`: The key name in the model object.
+- `label`: Form label description.
+- `component`: Native component identifier (e.g. `'input'`, `'select'`, `'switch'`, `'date-picker'`).
+- `props`: Target component props passed dynamically.
+- `formItemProps`: Props passed directly to the containing `YhFormItem` (e.g. `labelWidth`).
+- `required` / `rules`: Form validation constraints.
+- `hidden`: A boolean or function `(model) => boolean` determining field visibility.
+- `disabled`: A boolean or function `(model) => boolean` determining disabled state.
+- `span` / `col`: Control grid widths (e.g. `12` for half column, `24` for full width).
+- `asyncOptions`: Fetch options dynamically from APIs.
+- `render`: A custom function `(h, { model, field }) => VNode` for custom render logic.
+- `type`: Set to `'list'` for repeatable sub-form fields.
 
-## Pattern: Dynamic Form
+## Pattern: Advanced Dynamic Form
 
 ```vue
 <script setup lang="ts">
-import { ref } from 'vue'
-import { YhButton, YhFormSchema, YhMessage } from '@yh-ui/components'
+import { ref, h } from 'vue'
+import { YhFormSchema, YhButton, YhMessage, YhInput } from '@yh-ui/components'
 import type { FormSchema } from '@yh-ui/components'
 
-const model = ref({
-  name: '',
-  role: '',
-  enabled: true
+// Define typed form state
+const formModel = ref({
+  projectName: '',
+  deploymentType: 'cloud',
+  cloudProvider: '',
+  scaleNodes: 3,
+  environments: [{ name: 'staging', domain: 'staging.company.com' }]
 })
 
+// Define schema configuration
 const schema: FormSchema = [
   {
-    field: 'name',
-    label: 'Name',
+    field: 'projectName',
+    label: 'Project Name',
     component: 'input',
     required: true,
-    props: { clearable: true, placeholder: 'User name' }
+    span: 24, // Full width row
+    props: {
+      placeholder: 'Enter project name',
+      clearable: true
+    }
   },
   {
-    field: 'role',
-    label: 'Role',
+    field: 'deploymentType',
+    label: 'Deployment Type',
     component: 'select',
     required: true,
+    span: 12,
+    props: {
+      options: [
+        { label: 'Cloud Hosted', value: 'cloud' },
+        { label: 'On-Premises', value: 'on-premise' }
+      ]
+    }
+  },
+  {
+    field: 'cloudProvider',
+    label: 'Cloud Provider',
+    component: 'select',
+    span: 12,
+    // Conditional visibility: only show if deploymentType is cloud
+    hidden: (model) => model.deploymentType !== 'cloud',
+    required: (model) => model.deploymentType === 'cloud',
     asyncOptions: async () => [
-      { label: 'Admin', value: 'admin' },
-      { label: 'Editor', value: 'editor' }
+      { label: 'AWS', value: 'aws' },
+      { label: 'Google Cloud Platform', value: 'gcp' },
+      { label: 'Microsoft Azure', value: 'azure' }
     ]
   },
   {
-    field: 'enabled',
-    label: 'Enabled',
-    component: 'switch',
-    defaultValue: true
+    field: 'scaleNodes',
+    label: 'Scale Nodes Count',
+    component: 'input-number',
+    span: 12,
+    props: {
+      min: 1,
+      max: 100
+    },
+    // Conditional disabled state: lock count if cloudProvider is not GCP
+    disabled: (model) => model.cloudProvider !== 'gcp'
+  },
+  {
+    field: 'customRenderer',
+    label: 'Custom Field',
+    span: 12,
+    // Custom render method returning standard VNode
+    render: (h, { model, field }) => {
+      return h(YhInput, {
+        modelValue: model[field],
+        'onUpdate:modelValue': (val: string) => {
+          model[field] = val
+        },
+        placeholder: 'Generated via render()'
+      })
+    }
+  },
+  {
+    field: 'divider1',
+    type: 'divider',
+    span: 24
+  },
+  {
+    field: 'environments',
+    label: 'Target Environments',
+    type: 'list', // Repeating sub-form group
+    span: 24,
+    props: {
+      // Define schemas for elements inside list array rows
+      schema: [
+        {
+          field: 'name',
+          label: 'Env Name',
+          component: 'input',
+          required: true,
+          span: 8
+        },
+        {
+          field: 'domain',
+          label: 'Access Domain',
+          component: 'input',
+          required: true,
+          span: 16
+        }
+      ]
+    }
   }
 ]
 
-function submit() {
-  YhMessage.success('Saved')
+const formRef = ref<InstanceType<typeof YhFormSchema> | null>(null)
+
+async function handleSave() {
+  if (!formRef.value) return
+
+  try {
+    const valid = await formRef.value.validate()
+    if (valid) {
+      YhMessage.success('Form configurations validated successfully!')
+      console.log('Final Model:', formModel.value)
+    }
+  } catch (err: any) {
+    YhMessage.error(`Validation failed: ${err.message || err}`)
+  }
+}
+
+function handleReset() {
+  formRef.value?.resetFields()
 }
 </script>
 
 <template>
-  <YhFormSchema
-    v-model="model"
-    :schema="schema"
-    :form-props="{ labelWidth: 120 }"
-    @submit="submit"
-  />
-  <YhButton type="primary" @click="submit">Save</YhButton>
+  <div class="form-container">
+    <!-- gutter specifies spacing between form grid components -->
+    <YhFormSchema
+      ref="formRef"
+      v-model="formModel"
+      :schema="schema"
+      :gutter="20"
+      :form-props="{ labelPosition: 'top' }"
+    />
+
+    <div class="form-buttons">
+      <YhButton type="primary" @click="handleSave">Submit Configuration</YhButton>
+      <YhButton @click="handleReset">Reset Fields</YhButton>
+    </div>
+  </div>
 </template>
 ```
 
 ## Agent Rules
 
-- Use `v-model` with `modelValue`.
-- Use `required` for simple required rules and `rules` for custom validation.
-- Use `hidden`/`disabled` functions for dynamic behavior.
-- Use `asyncOptions` for remote options instead of manually wiring loading state for each field.
-- Use `type: 'list'` for repeatable field groups.
-- Do not use `YhFormSchema` for a tiny static form unless schema generation is useful.
+- **Use Model Value**: Always bind data using `v-model` (equivalent to `v-model:modelValue`).
+- **Define Render Returns**: Custom field `render` methods must accept `h` function parameters and return a valid VNode using actual components imported from `@yh-ui/components`.
+- **List Sub-schema**: When using `type: 'list'`, nested schema arrays must be defined inside `props.schema`.
+- **Gutter Config**: Set layout spacings using the `:gutter` prop on the wrapper `YhFormSchema`.

package/assets/skills/yh-ui/references/recipes-icons.md

@@ -0,0 +1,126 @@
+# Deep Recipe: YH-UI Icons
+
+Use this recipe when integrating and rendering icons across YH-UI components. YH-UI uses a high-performance icon system based on Iconify, supporting thousands of icons with zero runtime overhead.
+
+## Default Choice
+
+Use the `Icon` component (aliased as `YhIcon`) from `@yh-ui/icons/vue` or `@yh-ui/icons`.
+
+## Usage Patterns
+
+### 1. Iconify String Name (Recommended)
+
+You can reference any icon using the standard `collection:icon` syntax. The package loads the icon asynchronously.
+
+```vue
+<script setup lang="ts">
+import { Icon } from '@yh-ui/icons/vue'
+</script>
+
+<template>
+  <!-- Material Design Icons collection -->
+  <Icon icon="mdi:home" />
+
+  <!-- Element Plus Icons collection -->
+  <Icon icon="ep:search" />
+
+  <!-- Lucide Icons collection -->
+  <Icon icon="lucide:settings" />
+</template>
+```
+
+### 2. Pre-registered Aliases
+
+You can use simplified short names for common UI actions (which resolve to pre-configured presets under the hood):
+
+```vue
+<template>
+  <Icon name="home" />
+  <!-- Resolves to mdi:home -->
+  <Icon name="search" />
+  <!-- Resolves to mdi:magnify -->
+  <Icon name="loading" />
+  <!-- Resolves to mdi:loading -->
+</template>
+```
+
+### 3. SVG Strings
+
+If you need to render raw SVG data dynamically without loading it from an external collection:
+
+```vue
+<script setup lang="ts">
+import { Icon } from '@yh-ui/icons/vue'
+
+const customSvg = '<path d="M12 2L2 22h20L12 2z" fill="currentColor"/>'
+</script>
+
+<template>
+  <Icon :svg="customSvg" />
+</template>
+```
+
+### 4. Custom Icon Components
+
+If you've imported raw Vue component icons from a local folder or another icon package:
+
+```vue
+<script setup lang="ts">
+import { Icon } from '@yh-ui/icons/vue'
+import CustomStarComponent from './CustomStar.vue'
+</script>
+
+<template>
+  <Icon :component="CustomStarComponent" />
+</template>
+```
+
+## Styling & Animations
+
+### Size and Color
+
+Adjust sizing (takes either numbers for pixel dimensions or CSS string values) and fill colors:
+
+```vue
+<template>
+  <Icon icon="mdi:heart" :size="24" color="var(--yh-color-danger)" />
+  <Icon icon="mdi:heart" size="2rem" color="#ff4d4f" />
+</template>
+```
+
+### Rotating & Spin Animations
+
+Apply static rotations or infinite spinning animations (highly useful for loading states):
+
+```vue
+<template>
+  <!-- Rotated 90 degrees -->
+  <Icon icon="mdi:chevron-right" :rotate="90" />
+
+  <!-- Infinite spin animation (1s full rotation) -->
+  <Icon icon="mdi:loading" spin />
+</template>
+```
+
+## Integration with YH-UI Components
+
+Many YH-UI components support passing an icon name directly or via slots:
+
+```vue
+<script setup lang="ts">
+import { YhButton, YhInput } from '@yh-ui/components'
+import { Icon } from '@yh-ui/icons/vue'
+</script>
+
+<template>
+  <!-- Passing icon prop -->
+  <YhButton type="primary" icon="mdi:plus">Add User</YhButton>
+
+  <!-- Custom slot rendering -->
+  <YhInput placeholder="Enter username">
+    <template #prefix>
+      <Icon icon="mdi:account" :size="16" />
+    </template>
+  </YhInput>
+</template>
+```