@wakastellar/ui 3.3.3 → 3.5.0

package/src/components/editor/blocks/waka-user-story-block.tsx

@@ -0,0 +1,295 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../../utils/cn"
+import type { PlateElementProps } from "../waka-editor-elements"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Slate node type for user story blocks */
+export const USER_STORY_BLOCK_TYPE = "user_story" as const
+
+/** Shape of a user story element in the Slate document */
+export interface UserStoryElement {
+  type: typeof USER_STORY_BLOCK_TYPE
+  /** The role ("As a ...") */
+  role: string
+  /** The action ("I want ...") */
+  action: string
+  /** The benefit ("So that ...") */
+  benefit: string
+  /** Optional story ID (e.g. "US-042") */
+  storyId?: string
+  /** Optional priority */
+  priority?: "must" | "should" | "could" | "wont"
+  /** Optional story points estimate */
+  points?: number
+  children: Array<{ text: string }>
+}
+
+/** Props for the WakaUserStoryBlock element renderer */
+export interface WakaUserStoryBlockProps extends PlateElementProps {
+  element?: UserStoryElement & Record<string, unknown>
+  /** Called when a field value changes */
+  onFieldChange?: (field: "role" | "action" | "benefit", value: string) => void
+}
+
+// ============================================================================
+// Priority config
+// ============================================================================
+
+const PRIORITY_CONFIG: Record<string, { label: string; color: string; bg: string }> = {
+  must: { label: "Must Have", color: "text-red-700 dark:text-red-400", bg: "bg-red-50 dark:bg-red-500/10" },
+  should: { label: "Should Have", color: "text-amber-700 dark:text-amber-400", bg: "bg-amber-50 dark:bg-amber-500/10" },
+  could: { label: "Could Have", color: "text-blue-700 dark:text-blue-400", bg: "bg-blue-50 dark:bg-blue-500/10" },
+  wont: { label: "Won't Have", color: "text-gray-500 dark:text-gray-400", bg: "bg-gray-50 dark:bg-gray-500/10" },
+}
+
+// ============================================================================
+// Field Row Component
+// ============================================================================
+
+interface FieldRowProps {
+  label: string
+  icon: React.ReactNode
+  value: string
+  placeholder: string
+  readOnly?: boolean
+  onChange?: (value: string) => void
+}
+
+function FieldRow({ label, icon, value, placeholder, readOnly, onChange }: FieldRowProps) {
+  return (
+    <div className="flex items-start gap-3 group">
+      <div className="flex items-center gap-1.5 pt-1 shrink-0 w-[90px]">
+        <span className="text-blue-500 dark:text-blue-400">{icon}</span>
+        <span className="text-[11px] font-semibold uppercase tracking-wider text-blue-600 dark:text-blue-400">
+          {label}
+        </span>
+      </div>
+      <div className="flex-1 min-w-0">
+        {readOnly ? (
+          <p className="text-sm text-foreground py-1">
+            {value || <span className="text-muted-foreground italic">{placeholder}</span>}
+          </p>
+        ) : (
+          <input
+            type="text"
+            value={value}
+            onChange={(e) => onChange?.(e.target.value)}
+            placeholder={placeholder}
+            className={cn(
+              "w-full bg-transparent text-sm text-foreground py-1 px-0",
+              "border-0 border-b border-transparent",
+              "focus:border-blue-300 dark:focus:border-blue-600",
+              "focus:outline-none transition-colors",
+              "placeholder:text-muted-foreground/50 placeholder:italic"
+            )}
+          />
+        )}
+      </div>
+    </div>
+  )
+}
+
+// ============================================================================
+// Element Component
+// ============================================================================
+
+/**
+ * WakaUserStoryBlock - A Plate.js block element for writing User Stories
+ * in the structured format "As a [role], I want [action], so that [benefit]".
+ *
+ * Each field is editable inline within the block. Renders with a distinctive
+ * visual treatment: blue left border, user icon, and structured layout.
+ *
+ * Register as a custom element in your Plate editor:
+ * ```ts
+ * const editor = usePlateEditor({
+ *   plugins: [...],
+ *   components: {
+ *     [USER_STORY_BLOCK_TYPE]: WakaUserStoryBlock,
+ *   },
+ * })
+ * ```
+ *
+ * Insert via slash command or programmatically:
+ * ```ts
+ * editor.insertNodes(createUserStoryNodes())
+ * ```
+ */
+export function WakaUserStoryBlock({
+  attributes,
+  children,
+  element,
+  className,
+}: WakaUserStoryBlockProps) {
+  const storyElement = element as UserStoryElement | undefined
+  const priority = storyElement?.priority
+  const storyId = storyElement?.storyId
+  const points = storyElement?.points
+
+  return (
+    <div
+      {...attributes}
+      contentEditable={false}
+      className={cn(
+        "relative my-4 rounded-lg overflow-hidden",
+        "border-l-4 border-blue-500 dark:border-blue-400",
+        "bg-blue-50/50 dark:bg-blue-950/20",
+        "border border-blue-200/60 dark:border-blue-800/40",
+        "shadow-sm hover:shadow-md transition-shadow duration-200",
+        className
+      )}
+    >
+      {/* Header bar */}
+      <div className="flex items-center justify-between px-4 py-2 bg-blue-100/50 dark:bg-blue-900/20 border-b border-blue-200/40 dark:border-blue-800/30">
+        <div className="flex items-center gap-2">
+          {/* User icon */}
+          <svg
+            className="h-4 w-4 text-blue-600 dark:text-blue-400"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth={2}
+            aria-hidden="true"
+          >
+            <path strokeLinecap="round" strokeLinejoin="round" d="M16 7a4 4 0 11-8 0 4 4 0 018 0zM12 14a7 7 0 00-7 7h14a7 7 0 00-7-7z" />
+          </svg>
+          <span className="text-xs font-bold uppercase tracking-wider text-blue-700 dark:text-blue-300">
+            User Story
+          </span>
+          {storyId && (
+            <span className="text-[10px] font-mono font-semibold text-blue-500 dark:text-blue-400 bg-blue-100 dark:bg-blue-800/40 px-1.5 py-0.5 rounded">
+              {storyId}
+            </span>
+          )}
+        </div>
+
+        <div className="flex items-center gap-2">
+          {/* Story points */}
+          {points !== undefined && (
+            <span className="inline-flex items-center justify-center h-5 min-w-[20px] px-1 rounded-full bg-blue-200 dark:bg-blue-700/50 text-[10px] font-bold text-blue-800 dark:text-blue-200">
+              {points}
+            </span>
+          )}
+
+          {/* Priority badge */}
+          {priority && PRIORITY_CONFIG[priority] && (
+            <span className={cn(
+              "text-[10px] font-semibold px-2 py-0.5 rounded-full",
+              PRIORITY_CONFIG[priority].bg,
+              PRIORITY_CONFIG[priority].color
+            )}>
+              {PRIORITY_CONFIG[priority].label}
+            </span>
+          )}
+        </div>
+      </div>
+
+      {/* Fields */}
+      <div className="px-4 py-3 space-y-2">
+        <FieldRow
+          label="As a"
+          icon={
+            <svg className="h-3 w-3" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2}>
+              <path strokeLinecap="round" strokeLinejoin="round" d="M16 7a4 4 0 11-8 0 4 4 0 018 0zM12 14a7 7 0 00-7 7h14a7 7 0 00-7-7z" />
+            </svg>
+          }
+          value={storyElement?.role || ""}
+          placeholder="role (e.g. platform administrator)"
+          readOnly
+        />
+        <FieldRow
+          label="I want"
+          icon={
+            <svg className="h-3 w-3" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2}>
+              <path strokeLinecap="round" strokeLinejoin="round" d="M13 10V3L4 14h7v7l9-11h-7z" />
+            </svg>
+          }
+          value={storyElement?.action || ""}
+          placeholder="action (e.g. to deploy services with one click)"
+          readOnly
+        />
+        <FieldRow
+          label="So that"
+          icon={
+            <svg className="h-3 w-3" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2}>
+              <path strokeLinecap="round" strokeLinejoin="round" d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
+            </svg>
+          }
+          value={storyElement?.benefit || ""}
+          placeholder="benefit (e.g. I can reduce time-to-market)"
+          readOnly
+        />
+      </div>
+
+      {/* Editable Slate children (hidden, required by Plate) */}
+      <div className="hidden">{children}</div>
+    </div>
+  )
+}
+
+WakaUserStoryBlock.displayName = "WakaUserStoryBlock"
+
+// ============================================================================
+// Node Factory
+// ============================================================================
+
+/**
+ * Creates the Slate nodes for inserting a user story block.
+ *
+ * @param options - Optional pre-fill values
+ * @returns Array of Slate nodes to insert
+ */
+export function createUserStoryNodes(options?: {
+  role?: string
+  action?: string
+  benefit?: string
+  storyId?: string
+  priority?: "must" | "should" | "could" | "wont"
+  points?: number
+}): UserStoryElement[] {
+  return [
+    {
+      type: USER_STORY_BLOCK_TYPE,
+      role: options?.role || "",
+      action: options?.action || "",
+      benefit: options?.benefit || "",
+      storyId: options?.storyId,
+      priority: options?.priority,
+      points: options?.points,
+      children: [{ text: "" }],
+    },
+  ]
+}
+
+/**
+ * Creates a Plate plugin configuration for user story blocks.
+ * Use with dynamic import for tree-shaking.
+ *
+ * @example
+ * ```ts
+ * const userStoryPlugin = await createUserStoryPlugin()
+ * // Add to editor plugins
+ * ```
+ */
+export async function createUserStoryPlugin() {
+  try {
+    const { createPlatePlugin } = await import("platejs/react")
+    return createPlatePlugin({
+      key: USER_STORY_BLOCK_TYPE,
+      node: {
+        isElement: true,
+        isVoid: true,
+        type: USER_STORY_BLOCK_TYPE,
+        component: WakaUserStoryBlock,
+      },
+    })
+  } catch {
+    console.warn("[WakaUserStoryBlock] platejs not installed")
+    return null
+  }
+}