minka-ds 0.4.1 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minka-ds",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Minka product design system — tokenized component library",
   "license": "MIT",
   "files": [

package/src/components/ui/flow-diagram.tsx

@@ -2,6 +2,14 @@
 
 import * as React from "react"
 
+/** Brand pair used to give a node / the flow a semantic accent. */
+export type FlowAccent =
+  | "yellow-darkforest"
+  | "rose-coral"
+  | "blue-navy"
+  | "beige-bronze"
+  | "gray-black"
+
 export interface FlowNode {
   /** Node label (party name). */
   name: string
@@ -13,6 +21,18 @@ export interface FlowNode {
   subtitle?: string
   /** True when this node is an unfilled slot (e.g. nothing selected yet). */
   empty?: boolean
+  /** Optional leading icon (used by state nodes like issue/destroy). */
+  icon?: React.ReactNode
+  /**
+   * When set, this node is a "state" node (no balance) rendered in the pair's
+   * colors — used for the abstract create/destroy end of issue/destroy flows.
+   */
+  accent?: FlowAccent
+  /**
+   * Invert the accent fill: light member as background, dark as text/border
+   * (instead of dark bg + light text). Used to contrast destroy vs issue.
+   */
+  accentInverted?: boolean
 }
 
 type FormatFn = (n: number) => string
@@ -55,6 +75,11 @@ export interface FlowDiagramProps {
   format?: FormatFn
   /** Optional content rendered below the diagram (e.g. a reference pill). */
   footer?: React.ReactNode
+  /**
+   * Semantic accent (brand pair) for the flow — tints the arrow, sheen and
+   * amount chip. Used by issue/destroy to read as generative/destructive.
+   */
+  accent?: FlowAccent
 }
 
 /**
@@ -65,12 +90,12 @@ export interface FlowDiagramProps {
  * an amount is entered. Unfilled nodes render as a dashed empty slot. Neutral
  * styling — suited to neutral transfers.
  */
-function FlowDiagram({ top, bottom, amount, direction, currency = "COP", format = defaultFormat, footer }: FlowDiagramProps) {
+function FlowDiagram({ top, bottom, amount, direction, currency = "COP", format = defaultFormat, footer, accent }: FlowDiagramProps) {
   const active = amount > 0
   const glintKey = active ? amount : 0
 
   return (
-    <div data-slot="flow-diagram" className="flex flex-col items-center">
+    <div data-slot="flow-diagram" className="relative flex flex-col items-center">
       <style>{`
         @keyframes flow-slide-in { from { opacity: 0; transform: translateY(6px); } to { opacity: 1; transform: translateY(0); } }
         @keyframes flow-pop { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } }
@@ -78,11 +103,15 @@ function FlowDiagram({ top, bottom, amount, direction, currency = "COP", format
 
       <FlowNodeCard key={top.empty ? "top-empty" : `top-${top.name}`} node={top} active={active} format={format} pop />
 
-      <Connector active={active} direction={direction} amount={amount} currency={currency} format={format} glintKey={glintKey} />
+      <Connector active={active} direction={direction} amount={amount} currency={currency} format={format} glintKey={glintKey} accent={accent} />
 
       <FlowNodeCard key={bottom.empty ? "bottom-empty" : `bottom-${bottom.name}`} node={bottom} active={active} format={format} pop />
 
-      {footer && <div className="mt-4">{footer}</div>}
+      {/* footer (e.g. reference pill) is absolutely positioned above the diagram
+          so it doesn't shift the diagram's vertical centering when it appears */}
+      {footer && (
+        <div className="absolute bottom-full left-1/2 -translate-x-1/2 mb-6">{footer}</div>
+      )}
     </div>
   )
 }
@@ -91,7 +120,7 @@ function FlowDiagram({ top, bottom, amount, direction, currency = "COP", format
 const CONNECTOR_H = 80
 
 function Connector({
-  active, direction, amount, currency, format, glintKey,
+  active, direction, amount, currency, format, glintKey, accent,
 }: {
   active: boolean
   direction: "up" | "down"
@@ -99,11 +128,15 @@ function Connector({
   currency: string
   format: FormatFn
   glintKey: number
+  accent?: FlowAccent
 }) {
   const gid = React.useId()
   const H = CONNECTOR_H
   const headUp = direction === "up"
 
+  // active stroke: semantic pair-dark when accented, else default ink
+  const activeStroke = accent ? `var(--color-pair-${accent}-dark)` : "var(--color-text-default)"
+
   const head = headUp ? "M2 6 L7 0 L12 6" : `M2 ${H - 6} L7 ${H} L12 ${H - 6}`
   const shapes = (
     <>
@@ -115,7 +148,7 @@ function Connector({
   return (
     <div className="relative flex items-center justify-center my-1" style={{ height: H }}>
       <svg width="14" height={H} viewBox={`0 0 14 ${H}`} className="block overflow-visible" aria-hidden>
-        <g stroke={active ? "var(--color-text-default)" : "var(--color-border-strong)"} strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" fill="none">
+        <g stroke={active ? activeStroke : "var(--color-border-strong)"} strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" fill="none">
           {shapes}
         </g>
         {active && (
@@ -165,6 +198,28 @@ function FlowNodeCard({ node, active, format, pop }: { node: FlowNode; active: b
     )
   }
 
+  // State node (issue/destroy abstract end): pair-colored, no balance. Icon sits
+  // inline next to the main label; subtext below.
+  if (node.accent) {
+    // default: dark fill + light text; inverted: light fill + dark text.
+    const fill = node.accentInverted ? `var(--color-pair-${node.accent}-light)` : `var(--color-pair-${node.accent}-dark)`
+    const ink  = node.accentInverted ? `var(--color-pair-${node.accent}-dark)` : `var(--color-pair-${node.accent}-light)`
+    const ring = node.accentInverted ? `var(--color-pair-${node.accent}-dark)` : `var(--color-pair-${node.accent}-light)`
+    const subInk = node.accentInverted ? "var(--color-text-default)" : "var(--color-text-inverse)"
+    return (
+      <div
+        className="flex flex-col items-center gap-1 [border-radius:var(--radius-card)] border px-5 py-3 text-center min-w-[180px]"
+        style={{ backgroundColor: fill, color: ink, borderColor: ring }}
+      >
+        <span className="flex items-center gap-1.5 text-body-sm">
+          {node.icon && <span className="flex items-center [&_svg]:size-4">{node.icon}</span>}
+          {node.name}
+        </span>
+        {node.subtitle && <span className="text-caption" style={{ color: subInk }}>{node.subtitle}</span>}
+      </div>
+    )
+  }
+
   return (
     <div
       className="flex flex-col items-center gap-1 [border-radius:var(--radius-card)] border border-[var(--color-border-default)] bg-[var(--color-bg-raised)] px-5 py-3 text-center min-w-[180px]"

package/src/components/ui/help-expander.tsx

@@ -0,0 +1,140 @@
+"use client"
+
+import * as React from "react"
+import { Popover as PopoverPrimitive } from "radix-ui"
+import { HelpCircle, X, ExternalLink } from "lucide-react"
+import { cn } from "../../lib/utils"
+
+type Anchor = "bottom-right" | "bottom-left" | "top-right" | "top-left"
+
+export interface HelpExpanderProps {
+  /** Card heading. */
+  title: string
+  /** Card body (text or nodes). */
+  children: React.ReactNode
+  /**
+   * "popover" (default) floats the card next to the trigger (portaled — works
+   * anywhere). "inset" expands the card inside the nearest positioned container,
+   * frosting whatever is behind it — for panels with empty space to fill.
+   */
+  mode?: "popover" | "inset"
+  /** Trigger appearance. Defaults to a circular "?" icon button, no label. */
+  trigger?: { icon?: React.ReactNode; label?: string }
+  /** inset mode: which corner the button sits in / the card expands from. */
+  anchor?: Anchor
+  /** Optional doc link rendered under the body. */
+  docHref?: string
+  docLabel?: string
+  className?: string
+}
+
+const ANCHOR_POS: Record<Anchor, string> = {
+  "bottom-right": "bottom-3 right-3 items-end",
+  "bottom-left":  "bottom-3 left-3 items-start",
+  "top-right":    "top-3 right-3 items-end",
+  "top-left":     "top-3 left-3 items-start",
+}
+
+// shared trigger button
+function TriggerButton({ trigger, ...props }: { trigger?: HelpExpanderProps["trigger"] } & React.ComponentProps<"button">) {
+  const icon = trigger?.icon ?? <HelpCircle className="size-4" />
+  return (
+    <button
+      type="button"
+      aria-label="Help"
+      className={cn(
+        "flex items-center justify-center gap-1.5 [border-radius:var(--radius-button)] border border-[var(--color-border-default)] bg-[var(--color-bg-raised)] text-[var(--color-text-muted)] shadow-[var(--shadow-card)] transition-colors hover:text-[var(--color-text-default)] hover:border-[var(--color-border-strong)]",
+        trigger?.label ? "h-8 px-3 text-label-sm" : "size-8",
+      )}
+      {...props}
+    >
+      {icon}
+      {trigger?.label}
+    </button>
+  )
+}
+
+// shared frosted card body
+function CardBody({ title, children, docHref, docLabel, onClose }: {
+  title: string
+  children: React.ReactNode
+  docHref?: string
+  docLabel?: string
+  onClose: () => void
+}) {
+  return (
+    <div
+      className="w-full [border-radius:var(--radius-card)] border border-[var(--color-border-default)] backdrop-blur-md shadow-[var(--shadow-popover)] p-4 [animation:help-in_.2s_cubic-bezier(0.16,1,0.3,1)]"
+      style={{ backgroundColor: "color-mix(in srgb, var(--color-bg-overlay) 70%, transparent)" }}
+    >
+      <style>{`@keyframes help-in { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; transform: translateY(0); } }`}</style>
+      <div className="flex items-start justify-between gap-3">
+        <span className="text-heading-4-serif text-[var(--color-text-default)]">{title}</span>
+        <button
+          type="button"
+          aria-label="Close help"
+          onClick={onClose}
+          className="shrink-0 -mr-1 -mt-1 size-6 flex items-center justify-center rounded-[var(--radius-button)] text-[var(--color-text-muted)] hover:bg-[var(--color-action-ghost-hover)] hover:text-[var(--color-text-default)] transition-colors"
+        >
+          <X className="size-3.5" />
+        </button>
+      </div>
+      <div className="mt-1.5 text-caption text-[var(--color-text-muted)] leading-relaxed">{children}</div>
+      {docHref && (
+        <a
+          href={docHref}
+          target="_blank"
+          rel="noreferrer"
+          className="mt-2.5 inline-flex items-center gap-1 text-caption text-[var(--color-text-link)] hover:text-[var(--color-text-link-hover)]"
+        >
+          {docLabel ?? "Learn more"}
+          <ExternalLink className="size-3" />
+        </a>
+      )}
+    </div>
+  )
+}
+
+function HelpExpander({
+  title, children, mode = "popover", trigger, anchor = "bottom-right", docHref, docLabel, className,
+}: HelpExpanderProps) {
+  const [open, setOpen] = React.useState(false)
+
+  // ── inset: expands inside the nearest positioned container ──
+  if (mode === "inset") {
+    return (
+      <div className={cn("absolute z-10 flex flex-col w-[calc(100%-1.5rem)]", ANCHOR_POS[anchor], className)}>
+        {open ? (
+          <CardBody title={title} docHref={docHref} docLabel={docLabel} onClose={() => setOpen(false)}>
+            {children}
+          </CardBody>
+        ) : (
+          <TriggerButton trigger={trigger} onClick={() => setOpen(true)} />
+        )}
+      </div>
+    )
+  }
+
+  // ── popover: floats next to the trigger (portaled) ──
+  return (
+    <PopoverPrimitive.Root open={open} onOpenChange={setOpen}>
+      <PopoverPrimitive.Trigger asChild>
+        <TriggerButton trigger={trigger} className={className} />
+      </PopoverPrimitive.Trigger>
+      <PopoverPrimitive.Portal>
+        <PopoverPrimitive.Content
+          side="top"
+          align="end"
+          sideOffset={8}
+          className="z-[var(--z-popover)] w-72 outline-none"
+        >
+          <CardBody title={title} docHref={docHref} docLabel={docLabel} onClose={() => setOpen(false)}>
+            {children}
+          </CardBody>
+        </PopoverPrimitive.Content>
+      </PopoverPrimitive.Portal>
+    </PopoverPrimitive.Root>
+  )
+}
+
+export { HelpExpander }

package/src/index.ts

@@ -44,6 +44,7 @@ export * from "./components/ui/tabs"
 export * from "./components/ui/textarea"
 export * from "./components/ui/tooltip"
 export * from "./components/ui/flow-diagram"
+export * from "./components/ui/help-expander"
 
 // Brand textures + logo
 export * from "./textures"