@ekanos/cli 0.1.5 → 0.1.7

package/templates/skills/polish-widgets/references/patterns.md

@@ -0,0 +1,269 @@
+# Widget fix patterns — before → after
+
+Each pattern names the failure, then shows the smallest honest fix. All
+imports are `@ekanos/ui/*`; icons go through `@ekanos/ui/icon` (Font Awesome
+names — verify against the Free set). Everything sits inside the standard
+`Widget.Active` body from the SDK's compound API; these are the bodies, not
+the wrapper.
+
+## 1. Flat list row → row with a first read
+
+**Failure:** every field the same size, so nothing answers "what needs my
+attention?". Values styled like labels, metadata styled like values.
+
+```tsx
+// BEFORE — three spans, one weight
+{
+  invoices.map((inv) => (
+    <div key={inv.id} className="flex justify-between p-2 text-sm">
+      <span>{inv.customer}</span>
+      <span className="text-xs">{inv.dueDate}</span>
+      <span>{inv.amount}</span>
+    </div>
+  ));
+}
+```
+
+```tsx
+// AFTER — name leads, value anchors right, metadata recedes
+<div className="divide-border divide-y">
+  {invoices.map((inv) => (
+    <div key={inv.id} className="flex items-center gap-3 px-4 py-3">
+      <div className="min-w-0 flex-1">
+        <p className="truncate text-base font-medium">{inv.customer}</p>
+        <p className="text-muted-foreground text-sm">
+          Due {formatDate(inv.dueDate)}
+        </p>
+      </div>
+      <span className="shrink-0 text-right text-base font-semibold tabular-nums">
+        {formatCurrency(inv.amount)}
+      </span>
+    </div>
+  ))}
+</div>
+```
+
+Rules at work: `min-w-0 flex-1` + `truncate` so long names never push the
+value out; `shrink-0` + `tabular-nums` so amounts hold a column; rows own
+their padding (`px-4 py-3`), the container owns none.
+
+## 2. Bare stat grid → hero KPI with supporting stats
+
+**Failure:** four equal chips. The widget's one question ("how are we
+doing?") has no answer — every number claims the same importance.
+
+```tsx
+// BEFORE — nothing is the headline
+<div className="grid grid-cols-2 gap-2 p-4">
+  <div className="text-sm">Revenue: {revenue}</div>
+  <div className="text-sm">Orders: {orders}</div>
+  <div className="text-sm">Avg: {avg}</div>
+  <div className="text-sm">Refunds: {refunds}</div>
+</div>
+```
+
+```tsx
+// AFTER — one hero, a delta, the rest demoted to a footer strip
+<div className="flex flex-1 flex-col items-center justify-center px-4 py-6">
+  <span className="text-muted-foreground text-sm">Revenue this month</span>
+  <span className="text-3xl font-semibold tracking-tight tabular-nums">
+    {formatCurrency(revenue)}
+  </span>
+  <span
+    className={cn(
+      'mt-1 text-sm font-medium',
+      delta >= 0 ? 'text-success-strong' : 'text-destructive',
+    )}
+  >
+    {delta >= 0 ? '+' : ''}
+    {delta.toFixed(1)}% vs last month
+  </span>
+</div>
+
+<div className="flex shrink-0 items-center border-t">
+  {[
+    { label: 'Orders', value: orders },
+    { label: 'Avg order', value: formatCurrency(avg) },
+    { label: 'Refunds', value: refunds },
+  ].map((stat, i) => (
+    <Fragment key={stat.label}>
+      {i > 0 && <div className="bg-border h-8 w-px" />}
+      <div className="flex flex-1 flex-col items-center py-3">
+        <span className="text-lg font-semibold tabular-nums">{stat.value}</span>
+        <span className="text-muted-foreground text-xs">{stat.label}</span>
+      </div>
+    </Fragment>
+  ))}
+</div>
+```
+
+(`cn` from `@ekanos/ui/utils`.) Pick the hero by the interview's SEE-outcome,
+not by which number is largest. One `text-3xl` element per widget — two heroes
+is zero heroes.
+
+## 3. Unstyled status → semantic badge or dot
+
+**Failure:** status as bare text, or hardcoded palette (`bg-green-500`) that
+breaks in dark mode and off-brand tenants.
+
+```tsx
+// BEFORE
+<span className="text-xs">{sub.status}</span>
+// or
+<span className="rounded bg-green-500 px-1 text-white">{sub.status}</span>
+```
+
+```tsx
+// AFTER — Badge variants carry the semantics; the map is the single source
+import { Badge } from '@ekanos/ui/badge';
+
+const STATUS_VARIANT = {
+  active: 'success',
+  trialing: 'info',
+  past_due: 'warning',
+  canceled: 'destructive',
+} as const;
+
+<Badge variant={STATUS_VARIANT[sub.status] ?? 'outline'}>
+  {STATUS_LABEL[sub.status] ?? sub.status}
+</Badge>;
+```
+
+When a badge is too loud (dense lists), use a dot plus muted text instead:
+
+```tsx
+<span
+  className={cn(
+    'h-2.5 w-2.5 shrink-0 rounded-full',
+    sub.status === 'active' ? 'bg-success' : 'bg-muted-foreground/40',
+  )}
+/>
+<span className="text-muted-foreground text-sm">{STATUS_LABEL[sub.status]}</span>
+```
+
+One status treatment per row. A row with a colored badge AND a colored icon
+AND colored money is signalling nothing.
+
+## 4. Cramped card → sizing floors applied
+
+**Failure:** `p-2`, `space-y-1`, `text-xs` everywhere, `h-3 w-3` icons. Dense
+is not information-rich; it is unreadable.
+
+```tsx
+// BEFORE
+<div className="space-y-1 p-2">
+  {events.map((e) => (
+    <div key={e.id} className="flex gap-1 text-xs">
+      <Icon name="fa-light fa-bolt" className="h-3 w-3" />
+      <span>{e.title}</span>
+    </div>
+  ))}
+</div>
+```
+
+```tsx
+// AFTER — floors: rows px-4 py-3, icons h-5 w-5, body text-sm+
+<div className="divide-border divide-y">
+  {events.slice(0, 6).map((e) => (
+    <div key={e.id} className="flex items-start gap-3 px-4 py-3">
+      <span className="bg-muted text-muted-foreground shrink-0 rounded-full p-2">
+        <Icon name={eventIcon(e.type)} className="h-5 w-5" />
+      </span>
+      <div className="min-w-0 flex-1">
+        <p className="truncate text-base font-medium">{e.title}</p>
+        <p className="text-muted-foreground text-sm">{e.summary}</p>
+      </div>
+      <span className="text-muted-foreground shrink-0 text-xs">
+        {formatTimeAgo(e.at)}
+      </span>
+    </div>
+  ))}
+</div>
+```
+
+If the content no longer fits after applying floors, show fewer items — the
+floors are not negotiable, the item count is.
+
+## 5. Overflowing card → inner scroll + "View all"
+
+**Failure:** the list grows the card past its grid slot, or a fixed
+`max-h-[180px]` caps it arbitrarily and clips the last row.
+
+```tsx
+// BEFORE — the card scrolls (or grows); a magic pixel height fights the grid
+<div className="max-h-[180px] overflow-y-auto">{rows}</div>
+```
+
+```tsx
+// AFTER — the LIST scrolls inside the flex column; the card holds its size
+import { Button } from '@ekanos/ui/button';
+
+<div className="flex h-full min-h-0 flex-col">
+  <div className="min-h-0 flex-1 overflow-y-auto">
+    <div className="divide-border divide-y">{rows}</div>
+  </div>
+  {items.length > 7 && (
+    <div className="shrink-0 border-t px-4 py-2">
+      <Button variant="ghost" size="sm" className="text-muted-foreground">
+        View all {items.length}
+      </Button>
+    </div>
+  )}
+</div>;
+```
+
+`min-h-0` is the load-bearing class — without it the flex child refuses to
+shrink and nothing scrolls. Test at the sm viewport preset, where the failure
+actually shows.
+
+## 6. Button pile-up → one action + menu
+
+**Failure:** two or three buttons per row; the row becomes a toolbar.
+
+```tsx
+// AFTER — one visible action, the rest behind a menu
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@ekanos/ui/dropdown-menu';
+
+<div className="flex shrink-0 items-center gap-2">
+  <Button size="sm">Pay now</Button>
+  <DropdownMenu>
+    <DropdownMenuTrigger
+      render={<Button variant="ghost" size="icon" className="h-8 w-8" />}
+    >
+      <Icon name="fa-light fa-ellipsis-vertical" className="h-4 w-4" />
+    </DropdownMenuTrigger>
+    <DropdownMenuContent align="end">
+      <DropdownMenuItem>View details</DropdownMenuItem>
+      <DropdownMenuItem>Payment history</DropdownMenuItem>
+    </DropdownMenuContent>
+  </DropdownMenu>
+</div>;
+```
+
+The one visible action should be the urgent one; if no action is urgent, all
+of them belong in the menu.
+
+## 7. Blank empty state → designed empty state
+
+**Failure:** an empty array renders an empty card, indistinguishable from a
+bug. Empty is a state you design, distinct from error.
+
+```tsx
+// AFTER — icon, one sentence of what appears here, what action produces it
+<div className="flex flex-1 flex-col items-center justify-center gap-3 p-8 text-center">
+  <div className="bg-muted flex h-16 w-16 items-center justify-center rounded-full">
+    <Icon name="fa-light fa-inbox" className="text-muted-foreground h-8 w-8" />
+  </div>
+  <p className="text-base font-medium">No invoices yet</p>
+  <p className="text-muted-foreground max-w-xs text-sm">
+    Invoices appear here as soon as your first one is issued.
+  </p>
+</div>
+```
+
+No CTA unless there is a real action the user can take from the dashboard.